Getting started

Installation

Install @codeatlasdev/ui and wire the theme into SvelteKit, Astro or plain Vite without a flash of the wrong theme.

CodeAtlas UI needs Svelte 5 (runes mode). In a SvelteKit or Astro app, bunx @codeatlasdev/ui init does the whole setup below for you (see The init command). Setup is three things: import the stylesheet once, inject the theme script before first paint, and start the colorScheme store in your root layout.

bun add @codeatlasdev/ui

npm install @codeatlasdev/ui

pnpm add @codeatlasdev/ui

The core bundle stays small. Heavy features are separate entry points with optional peer dependencies, so install only what you use:

@sveltejs/kit and astro are optional peers too: install the one your app uses. Icons come from @lucide/svelte, which the package already depends on.

Release channels

Releases are published by version tag (@codeatlasdev/ui@X.Y.Z), not from branches. The prerelease id in the version is the npm dist-tag.

A prerelease with another id (X.Y.Z-alpha.N, for example) is published under a dist-tag with that id. Pin an exact version (bun add @codeatlasdev/ui@3.1.0-beta.2) to keep a prerelease stable.

Every version is published from CI with an npm provenance statement, so you can check which commit and workflow built it (npm audit signatures).

The init command

bunx @codeatlasdev/ui init [--write] [--dir <path>]

init detects the framework from package.json (@sveltejs/kit means SvelteKit, otherwise astro means Astro) and prints Detected SvelteKit. or Detected Astro.. With neither it prints an error and exits with code 1. Then it goes through the files of that framework, one line each:

When diffs are pending it ends with N existing file(s) left untouched. Re-run with --write to apply the diffs above. A clean run ends with Done. Run your dev server: the theme paints on the first frame.

SvelteKit

@codeatlasdev/ui supports SvelteKit 2 (^2.12) and SvelteKit 3. The steps below are the same on both; the differences are in SvelteKit 3. init reads the installed Kit major (node_modules/@sveltejs/kit, or the range in package.json before install ran; anything it cannot parse counts as 2) and writes the right theme import.

What init writes

For each file below, init creates it when it is missing, except vite.config.ts and src/app.html, which it only patches (it prints skip when they are not there). A file that already exists is never overwritten: init prints a diff and applies it only with --write. Re-running it changes nothing once the setup is complete.

caErrorPlugin({ scaffold: true }) then creates src/routes/+error.svelte and src/error.html the first time Vite runs (dev or build), and never overwrites them. The result is the setup below, which you can also write by hand.

Full setup

SvelteKit 3

Kit 3 changed three things this setup touches. init handles the third (the theme import in the hook) and, for the other two, prints a note line instead of rewriting svelte.config.js or tsconfig.json: it reports svelte.config.js/.ts/.mjs when one exists, and a tsconfig.json that does not mention $app/tsconfig. On a clean Kit 3 run you get no Done. line while a note is pending.

1. Configuration moves into the Vite plugin. svelte.config.js is ignored (config_file_unsupported) and the kit namespace is gone (config_kit_namespace). Pass the options directly to sveltekit(), next to the two plugins:

   // vite.config.ts
   import adapter from "@sveltejs/adapter-auto";
   import { sveltekit } from "@sveltejs/kit/vite";
   import { caErrorPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
   import { defineConfig } from "vite";
   import { theme } from "./src/lib/theme.ts";
   
   export default defineConfig({
     plugins: [sveltekit({ adapter: adapter() }), caThemePlugin(theme), caErrorPlugin({ scaffold: true })],
   });

2. tsconfig.json extends $app/tsconfig. .svelte-kit/tsconfig.json is no longer generated (tsconfig_extends_missing):

   { "extends": "$app/tsconfig" }

3. $lib is removed (module_removed_lib). Use the #lib/* import that sv create adds to package.json ("imports": { "#lib/*": "./src/lib/*" }), written with the extension. In the hook, import the theme as #lib/theme.ts:

   // src/hooks.server.ts
   import { theme } from "#lib/theme.ts";

   Without a #lib map, use a relative path (./lib/theme.ts from src/hooks.server.ts). Everything else (the layout, the stylesheet import, colorScheme.init() and the viewport meta) is identical to Kit 2.

Astro

Use the integration together with @astrojs/svelte. caUI injects the theme into the <head> of every page and handles the SSR bundling. bunx @codeatlasdev/ui init sets this up for an Astro project:

bun add @codeatlasdev/ui @astrojs/svelte svelte

// astro.config.mjs
import svelte from "@astrojs/svelte";
import { caUI } from "@codeatlasdev/ui/astro";
import { defineConfig } from "astro/config";
import { theme } from "./src/theme.ts";

export default defineConfig({ integrations: [svelte(), caUI(theme)] });

// src/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/astro";

export const theme: ThemeOptions = { defaultPreset: "amber", defaultScheme: "system" };

Import the stylesheet once in your base layout, add the viewport meta and start the store from a client script, so theme switches and OS scheme changes stay in sync on the page:

---
// src/layouts/Base.astro
import "@codeatlasdev/ui/styles/global.css";
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
    <title>My app</title>
  </head>
  <body>
    <slot />
    <script>
      import { colorScheme } from "@codeatlasdev/ui";
      colorScheme.init();
    </script>
  </body>
</html>

Components are Svelte islands. Add a client directive to anything interactive (client:visible or client:load); purely visual components render on the server with no JavaScript. Call colorScheme.init() once per page, from that layout script or from one island that is always present.

Plain Vite

caThemePlugin also works without SvelteKit: it injects the theme head through transformIndexHtml.

// vite.config.ts
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { caThemePlugin } from "@codeatlasdev/ui/vite";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [caThemePlugin(), svelte()] });

// src/main.ts
import "@codeatlasdev/ui/styles/global.css";
import { colorScheme } from "@codeatlasdev/ui";
import { mount } from "svelte";
import App from "./App.svelte";

colorScheme.init();
mount(App, { target: document.getElementById("app")! });

Verify

<script>
  import { Button, ThemeToggle } from "@codeatlasdev/ui";
</script>

<Button variant="filled">It works</Button>
<ThemeToggle />

Reload with the toggle on dark and check that there is no white flash. Continue with Theming.