Getting Started

Quick Start with AI #

Paste this into your AI coding tool and let it handle the setup:

text
 
Install @astryx-svelte/core, @astryx-svelte/theme-neutral, and @astryx-svelte/cli in this project, then run `npx @astryx-svelte/cli init` to set up agent docs. Read the generated files to learn the conventions.

Install #

Astryx requires Svelte 5 or later: svelte >= 5.0.0 is the peer dependency of @astryx-svelte/core. Runes are used throughout, so there is no Svelte 4 compatibility mode.

Add the core package, a theme, StyleX and the CLI to your existing project. @stylexjs/stylex is a peer dependency rather than a bundled one because your own bundler compiles it — two copies at different versions render unstyled with no error.

bash
 
npm install @astryx-svelte/core @astryx-svelte/theme-neutral @stylexjs/stylex @astryx-svelte/cli
npm install -D @stylexjs/unplugin

These packages are versioned 0.3.0 and ready to publish, but they are **not on npm yet** — nothing resolves until the first npm publish. Until then, work from a clone of the repository: pnpm install, then node packages/cli/bin/astryx-svelte.mjs <command>.

Then run astryx-svelte init to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive; no prompts; so it's safe for AI agents, CI, and scripts. Add --all for pointers to the theme and page-building workflows.

bash
 
npx astryx-svelte init

Add the theme CSS #

Import the base stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties.

css
 
@import '@astryx-svelte/core/base.css';
@import '@astryx-svelte/theme-neutral/theme.css';

base.css is one file, not two: it declares the cascade layer order, sets color-scheme so every light-dark() token resolves, and contains the reset. Upstream ships the reset separately as an opt-in import; here the components are authored against it and misrender without it, so it is not optional.

Available themes: @astryx-svelte/theme-neutral (muted minimal, a good starting point), @astryx-svelte/theme-butter, @astryx-svelte/theme-chocolate, @astryx-svelte/theme-gothic (dark-only), @astryx-svelte/theme-liquid-glass, @astryx-svelte/theme-matcha, @astryx-svelte/theme-stone, and @astryx-svelte/theme-y2k. See astryx-svelte docs theme for the full theming guide.

These stylesheets are cascade-layered: the layer order is reset, astryx-base, astryx-theme, product. If your project has existing global CSS, a legacy reset, or Tailwind, assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in astryx-svelte docs migration before building screens.

Add your first component #

Every component is exported from the package root. There are no per-component subpath entrypoints — the barrel is tree-shaken by your bundler, and @astryx-svelte/core is where Button lives. The subpaths that do exist are for non-component surfaces: ./theme, ./hooks, ./utils, ./i18n, ./naming, and ./base.css.

svelte
 
<script lang="ts">
	import { Button, VStack } from '@astryx-svelte/core';
</script>
​
<VStack gap={2}>
	<Button label="Hello Astryx" onclick={() => alert('Hi!')} />
</VStack>

Customize with StyleX #

Astryx components support various styling solutions, from plain CSS and a scoped <style> block to Tailwind utilities and the class prop. See astryx-svelte docs styling for the full guide. Astryx also has a deep integration with StyleX, an atomic CSS-in-JS library: create styles with stylex.create() and pass them to components with the xstyle prop.

StyleX must be imported from a .ts module, never from a .svelte file — the bundler plugin Babel-parses anything that imports @stylexjs/stylex, and it would read Svelte markup as JSX. So the styles live in a sibling .stylex.ts and the component imports the object.

ts
 
import * as stylex from '@stylexjs/stylex';
​
export const overrides = stylex.create({
	save: { alignSelf: 'flex-end', marginTop: 16 }
});

svelte
 
<script lang="ts">
	import { Button } from '@astryx-svelte/core';
	import { overrides } from './page.stylex.js';
</script>
​
<Button label="Save" xstyle={overrides.save} />

Explore the CLI #

The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:

json
 
"scripts": {
  "astryx-svelte": "node node_modules/@astryx-svelte/cli/bin/astryx-svelte.mjs"
}

Then discover what's available:

bash
 
astryx-svelte component          # list all components
astryx-svelte component Button   # props, usage, theming for Button
astryx-svelte util               # list all utils (runes-based composables)
astryx-svelte docs               # list all doc topics
astryx-svelte template --list    # available page templates
astryx-svelte docs tokens        # spacing, color, radius reference