Getting Started

Prerequisites

Stella UI requires the following peer dependencies:

• React 18 or 19
• A bundler that supports CSS Modules and ESM (Vite, Next.js, etc.)

Installation

npm

npm install @stella-ds/react @stella-ds/theme

pnpm

pnpm add @stella-ds/react @stella-ds/theme

yarn

yarn add @stella-ds/react @stella-ds/theme

Theme Setup

Stella UI components rely on --stella-* CSS custom properties. You must inject them once at the root of your application. There are two ways:

Option A — CSS import (recommended)

Import the pre-built CSS file in your root layout or entry point:

import '@stella-ds/theme/css'

Option B — JavaScript injection

For dynamic injection (useful in JS-only environments or when bundler CSS imports are not available):

import { injectCSSVars } from '@stella-ds/theme'

// Call once before first render
injectCSSVars()

Option C — Raw token object

Access the full token map for programmatic use:

import { cssVariables, tokens } from '@stella-ds/theme'

// cssVariables: Record<string, string>  — { '--stella-color-cosmos-500': '#4f46e5', ... }
// tokens: nested object matching the tokens.json structure

Basic Usage

After setting up the theme, import components directly from @stella-ds/react:

import '@stella-ds/theme/css'
import { Button, Input, Card, CardContent } from '@stella-ds/react'

export default function ContactForm() {
  return (
    <Card>
      <CardContent>
        <Input placeholder="Your email" size="md" />
        <Button variant="solid" size="md">
          Subscribe
        </Button>
      </CardContent>
    </Card>
  )
}

Next.js Integration

App Router (Next.js 13+)

All @stella-ds/react components are Client Components (they include the "use client" directive via the tsup build banner). Import them freely in Server Components — Next.js will automatically handle the boundary.

// app/layout.tsx
import '@stella-ds/theme/css'   // ← import theme in root layout

// app/page.tsx (Server Component)
import { Button } from '@stella-ds/react'  // ✅ works fine

export default function Page() {
  return <Button variant="glow">Hello from Server Component</Button>
}

Pages Router (Next.js 12 and below)

// pages/_app.tsx
import '@stella-ds/theme/css'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Tip: Static Export

Stella UI works with output: 'export' (static generation). No server-side APIs are used.

TypeScript

Full TypeScript definitions are included — no @types/* packages needed. All props are strictly typed with discriminated unions for variant/size enums.

Next Steps