Installation

Set up StyleX and the arene theme in a Vite + React project.

You don't install arene from npm. You add each component to your project as a source file, with the shadcn CLI or by copying it from these docs, and then edit it like any other file.

Before you add the first component, set up StyleX and add arene's theme files. The arene setup is written and tested for Vite + React + TypeScript. Other bundlers are not documented. File paths are relative to src/.

Follow every step, then render a component to check the setup. A successful build does not prove that the styles are correct.

Setup

Run the setup item. It writes components.json with the @arene registry, theme.css, interop.css and the theme modules, then installs the StyleX runtime, the fonts and the compiler.

pnpm dlx shadcn@latest add https://www.arene.style/r/init.json

Don't run shadcn init. It requires Tailwind, and the setup item writes the same components.json.

The remaining steps edit files your project already has. The CLI can't edit them, so you do these steps on both paths.

Add the StyleX plugin to your Vite config. Put it first in the array, so it compiles your source before the React plugin transforms it.

vite.config.ts
import path from "node:path"
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import stylex from "@stylexjs/unplugin/vite"

export default defineConfig({
  plugins: [
    stylex({
      aliases: { "@/*": [path.join(import.meta.dirname, "src/*")] },
      useCSSLayers: { before: ["arene.base"] },
    }),
    react(),
  ],
  resolve: { tsconfigPaths: true },
  build: { cssTarget: ["chrome123", "edge123", "firefox120", "safari17.5"] },
})

You need all four options:

  • aliases lets the compiler resolve @/theme/tokens.stylex. Without it the build fails with "Could not resolve the path to the imported file".
  • useCSSLayers puts the reset layer from theme.css under every StyleX class. Without it the reset's * { margin: 0 } overrides every StyleX declaration.
  • resolve.tsconfigPaths lets Vite resolve the same @/ imports.
  • build.cssTarget stops Vite's CSS minifier from rewriting light-dark(), which every color token uses.

The plugin appends the compiled CSS to your bundle. You don't need an @import or a virtual module.

Set browserslist. The StyleX compiler passes it to lightningcss as the target. With the default list, lightningcss replaces light-dark() with a polyfill that only works in a production bundle, so the color tokens stop working in dev. The list below is Baseline 2024, the same browser versions as cssTarget above.

package.json
{
  "browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5"]
}

Point @/* at src/ in both tsconfig.json and tsconfig.app.json. Vite and TypeScript read tsconfig.app.json. The shadcn CLI reads only the root file to decide where a component goes, and without the alias there it writes into a folder literally named @. If you copy by hand, nothing reads the root entry.

tsconfig.json
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}
tsconfig.app.json
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

In tsconfig.node.json, which type-checks vite.config.ts, set "module": "esnext" and "moduleResolution": "bundler". Under the template's nodenext, TypeScript reads the StyleX plugin's default export as a namespace, and tsc -b fails with "This expression is not callable".

Delete the template's src/index.css and its import. It sets --border and color-scheme on :root outside any layer, which overrides arene's values. Then import both stylesheets at the top of your entry file, theme.css first.

main.tsx
import "./styles/theme.css"
import "./styles/interop.css"

Add your first component. The CLI also adds the arene components and helpers it imports, and installs its npm dependencies.

pnpm dlx shadcn@latest add @arene/button

Without the CLI, follow the Manual tab on the component's page.

Then render it and check that it is styled. A missing compiler alias throws. An alias pointing at the wrong existing file leaves an undefined hashed var() in the CSS. Add the lint and build checks to catch these mistakes in your project.

The first vite start after installing can show an "Invalid empty selector" overlay from the StyleX plugin. Reload the page once. The production build is not affected.

Existing components.json

If the project already has a components.json, the setup item would ask to overwrite it. Add the registry to your existing file instead, then add the theme and the compiler:

pnpm dlx shadcn@latest registry add @arene=https://www.arene.style/r/{name}.json
pnpm dlx shadcn@latest add @arene/theme
pnpm add -D @stylexjs/unplugin

Then make the edits under Setup, from the Vite config on.

Set "rsc": true in components.json. With false, the CLI strips "use client" from about half the files it writes, and --diff reports changes that aren't there. Vite ignores the directive. Leave tailwind.cssVariables at its default, true.

Don't add arene to a project that uses shadcn/ui components. Both write button.tsx, input.tsx, dialog.tsx, label.tsx, field.tsx and more into the same ui alias, so arene's files overwrite shadcn/ui's. Both also define --background, --foreground, --border, --card, --muted, --primary, --ring, --font-sans and --font-mono on :root. This path is for a components.json that pulls from other registries.

Updating

Nothing updates a component after you add it. To see what changed upstream, run add with --diff and the file's path. Without a path, the CLI shows only the first five files.

pnpm dlx shadcn@latest add @arene/button --diff src/components/ui/button.tsx

To get new theme modules such as widths.ts and visibility.ts, add the theme without --overwrite and decline replacement of files you have edited:

pnpm dlx shadcn@latest add @arene/theme

For new entries in existing files, such as states.ts or tokens.stylex.ts, compare the upstream source in Setup and merge the missing entries into your local files before using the updated component. Declining replacement keeps the old file, so it does not add those entries.

Or copy the missing modules from Setup. Adding a component does not bring new theme modules because theme imports are skipped as dependencies.

--overwrite rewrites the component, along with the arene components and helpers it pulls in. It never writes the theme files, so it keeps your edits to tokens.stylex.ts. To get theme updates, re-run the setup item or add the theme with --overwrite. Both replace your edits to the token files.

pnpm dlx shadcn@latest add @arene/theme --overwrite

Writing UI

Read Styling for overrides, tokens and checks, and Layout for composing a page. Theming explains changing tokens, scoping a theme and dark mode.

Field state

Field shares its state with its layout parts through field-state.ts. The CLI adds the file with any component that imports it. If you copy by hand, copy it from here when a component's manual steps name it.

lib/field-state.ts
"use client"

import { createContext } from "react"
import type { Field } from "@base-ui/react/field"

export const FieldStateContext = createContext<Field.Root.State | null>(null)