Installation

Install the package, import one stylesheet, wrap your app. That's the whole setup.

Requirements#

Astralis ships precompiled CSS: every class any component can emit is already in the stylesheet, generated and verified at the library's own build time. Your bundler just serves a .css file.

The short way#

The CLI does all three steps below for you. For a new project:

npx astralis-cli create my-app

It runs the official create-next-app or create-vite prompts, then wires Astralis into the result: stylesheet imported, provider mounted, ready to run. For a project you already have:

npx astralis-cli init

Same edits, made in place. Pass --dry-run to see them first.

If you'd rather do it by hand, or the CLI doesn't recognise your setup, the three steps are below. That's all init is doing.

1. Install the package#

pnpm add astralis-ui
# or: npm install astralis-ui / yarn add astralis-ui

2. Import the stylesheet (once)#

import "astralis-ui/styles.css";

Do this at your app's entry point (root layout in Next.js, main.tsx in Vite). One import covers every component, both themes and all responsive variants.

3. Wrap your app in the provider#

import { AstralisProvider } from "astralis-ui";

export function App({ children }) {
  return <AstralisProvider defaultTheme="system">{children}</AstralisProvider>;
}

AstralisProvider owns theming: it resolves light/dark (including the "system" preference), persists the user's choice to localStorage, and, if you pass a brand color, derives the full shade scale at runtime. Details on the Theming page.

Next.js (App Router)#

Import the stylesheet and mount the provider in your root layout. The provider is a client component, but your pages stay server components: children pass straight through.

// app/layout.tsx
import { AstralisProvider } from "astralis-ui";
import "astralis-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <AstralisProvider defaultTheme="system">{children}</AstralisProvider>
      </body>
    </html>
  );
}

Avoiding the dark-mode flash#

The provider applies the .astralis-dark class after hydration, so a user who prefers dark can see one light-themed frame first. To paint dark from the very first frame, run this tiny inline script before the body renders (it reads the same storage key the provider uses):

const themeInit = `(function(){try{var t=localStorage.getItem("astralis-ui-theme");var d=t==="dark"||((!t||t==="system")&&window.matchMedia("(prefers-color-scheme: dark)").matches);if(d)document.documentElement.classList.add("astralis-dark");}catch(e){}})();`;

// inside <body>, before your app:
<script dangerouslySetInnerHTML={{ __html: themeInit }} />

This documentation site uses exactly this pattern.

Vite / SPA#

// src/main.tsx
import { createRoot } from "react-dom/client";
import { AstralisProvider } from "astralis-ui";
import "astralis-ui/styles.css";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <AstralisProvider defaultTheme="system">
    <App />
  </AstralisProvider>,
);

Using Astralis alongside your own styling#

Whatever your app already uses (a utility framework, CSS Modules, plain stylesheets), Astralis coexists with it. Every Astralis class is namespaced under an astralis: prefix internally, so the library's styles can never collide with your own, and your styling setup never needs to know Astralis exists. You can also pass your own classes to any component via className; see Style Props for how conflicts are resolved.

Tree-shaking#

The package publishes one ES module per component with a sideEffects declaration, so bundlers drop everything you don't import. Importing a Button ships the Button, not the library.

Tooling#

Two things worth setting up once, both covered on their own pages:

• The CLI: beyond create and init, it copies blocks into your project (npx astralis-cli add dashboard-01) and generates a static theme stylesheet from a brand seed.
• AI agents: npx astralis-cli connect-mcp points your coding agent at a server that serves these docs, so it writes against the current component API instead of guessing at one.

Next: the Quick Start builds a working form in about twenty lines.