Getting Started
↓

Installation

Scaffold a pre-wired project in one command, or wire an existing project manually — your choice.

✦
The fastest path is the CLI: npx stareezy create my-app --template next. It scaffolds a fully wired project with stareezy.config.ts, the compiler plugin, and ThemeProvider already set up.

Option A — CLI (recommended)

The @stareezy-ui/cli scaffolds a pre-wired starter project for Next.js, Vite, or Expo. No manual wiring — everything is ready to run.

Create a new project
npx @stareezy-ui/cli create my-app --template next
cd my-app
npm install
npm run dev
yarn create stareezy my-app --template next
cd my-app
yarn install
yarn dev
pnpm create stareezy my-app --template next
cd my-app
pnpm install
pnpm dev

Next.js 15 (App Router)

npx stareezy create my-app --template next
cd my-app
pnpm install
pnpm dev

Vite + React 19

npx stareezy create my-app --template vite
cd my-app
npm install
npm run dev

Expo SDK 56

npx stareezy create my-app --template expo
cd my-app
yarn install
expo start
Each template ships with
  • ◈stareezy.config.ts with media breakpoints and shorthands pre-configured
  • ◈Compiler wiring (Vite plugin for Next.js/Vite, Metro transformer for Expo)
  • ◈ThemeProvider wrapping the app root
  • ◈A curated set of components ready to use
ℹ
If you already have a project, run npx stareezy init to add just the wiring. It is idempotent — safe to run multiple times.

Option B — Manual

Install the packages individually and wire them yourself.

Requirements

⬡Node.js 18+
◈pnpm 9+ / npm / yarn
⚛React 18 or 19
TSTypeScript 5+

Install packages

npm
yarn
pnpm
# Tokens only (zero dependencies)
pnpm add @stareezy-ui/tokens

# Full component library
pnpm add @stareezy-ui/tokens @stareezy-ui/components @stareezy-ui/runtime

# Build-time compiler (Vite, Babel, or Metro)
pnpm add -D @stareezy-ui/compiler

Setup

1
Create stareezy.config.ts

Create a config file at your project root. This is read by the compiler automatically and registers your themes, tokens, breakpoints, and shorthands.

// stareezy.config.ts
import { createUi, themes } from '@stareezy-ui/tokens'

export const ui = createUi({
  themes: {
    aurora:        themes.aurora,
    dark:          themes.dark,
    light:         themes.light,
    'steins-gate': themes['steins-gate'],
    quasar:        themes.quasar,
  },
  media: { sm: 480, md: 768, lg: 1024, xl: 1280, '2xl': 1536 },
  shorthands: {
    p: 'padding', m: 'margin', br: 'borderRadius', w: 'width',
  } as const,
})

declare module '@stareezy-ui/tokens' {
  interface SzrCustomConfig extends typeof ui {}
}

export default ui
2
Add the compiler plugin

Next.js — in next.config.ts:

import { stareezyVitePlugin } from '@stareezy-ui/compiler'
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack(config) {
    config.plugins.push(stareezyVitePlugin())
    return config
  },
}
export default nextConfig

Vite — in vite.config.ts:

import { stareezyVitePlugin } from '@stareezy-ui/compiler'
export default { plugins: [stareezyVitePlugin()] }

Expo / Metro — in metro.config.js:

const { getDefaultConfig } = require('expo/metro-config')
const config = getDefaultConfig(__dirname)
config.transformer = {
  ...config.transformer,
  babelTransformerPath: require.resolve('@stareezy-ui/compiler/metro'),
}
module.exports = config
3
Wrap your app with ThemeProvider
ThemeProvider setup
import './stareezy.config'  // must be first import
import { ThemeProvider } from '@stareezy-ui/tokens'

export default function App({ children }) {
  return (
    <ThemeProvider defaultTheme="aurora">
      {children}
    </ThemeProvider>
  )
}
ℹ
For Next.js App Router, wrap ThemeProvider in a "use client" component. See the Server Components guide for the full pattern.
4
Verify
✦Components resolve to the current theme's values at render time via t.* props.
import { t } from '@stareezy-ui/tokens'
import { Box, Text, Button } from '@stareezy-ui/components'

function Test() {
  return (
    <Box bg={t.backgrounds.secondary} p={16} rounded={8}>
      <Text type="M-heading-bold" text="Stareezy UI is working!" />
      <Button type="Primary" text="Click me" />
    </Box>
  )
}
✦
The compiler is optional — components work without it using the runtime adapter. The compiler gives you better performance by extracting atomic CSS at build time.

Compatibility

FrameworkSupported versions
React
18, 19
React Native
0.81 – 0.86
Expo SDK
54, 55, 56
Next.js
14, 15, 16
Vite
4, 5, 6, 7

See the Compatibility guide for full details and installation instructions per framework.