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.
Install the runtime packages, then the compiler as a dev dependency.
Copy theme.css. It holds the element reset, the color-scheme switch that
controls dark mode, and the font stacks.
Copy the token module. Colors are defineVars, and each one is a
light-dark() pair. The fixed scales, such as space, radius, width, text and
shadow, are defineConsts. The interop group publishes the flat custom
properties that theme.css reads. See Theming before changing these values.
Copy the breakpoints. In StyleX a media query is a key inside a property's value, not a block around the rule, so a breakpoint is a constant you import.
Copy the markers. A marker lets a part read an ancestor's state. An accordion's
chevron uses one to change when its trigger is hovered. StyleX only compiles
markers declared in a .stylex.ts file.
Copy the shared state styles: the focus ring, the invalid ring, the disabled dim and the two popup surfaces. Every component merges these into its own styles instead of repeating them.
Copy the width and visibility styles. Pass widths.xs through xstyle for a
full-width element capped at 20rem. The keys are narrow (12rem), xs (20rem),
sm (24rem), md (28rem), lg (32rem) and xl3 (48rem). These styles read
the width constants in tokens.stylex.ts. In a mixed style entry, read a
constant directly, such as maxWidth: width.md, to keep the entry cohesive.
Choose a visibility style that names the element's visible display.
visibility.flexFromMd is hidden below 48rem and flex from 48rem upward;
visibility.flexBelowMd is flex below 48rem and hidden above it.
The inline-flex pair uses inlineFlexFromMd and inlineFlexBelowMd.
flexFromSm, blockFromSm, blockFromMd and blockFromXl show from 40rem,
40rem, 48rem and 80rem respectively. Each style writes both display states,
because StyleX replaces the whole display property when styles are merged.
Copy the state-styles helper. Base UI passes a part's state to className and
style callbacks, and stylex.props() returns both a class and a style. The
helper builds both callbacks from one list of styles, so a dynamic style keeps
its inline variable.
Copy interop.css. It holds the rules StyleX can't express: @property
registrations, the scroll-driven edge masks, sizing for icons inside components
and the drawer's gesture rules.
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.
You need all four options:
aliaseslets the compiler resolve@/theme/tokens.stylex. Without it the build fails with "Could not resolve the path to the imported file".useCSSLayersputs the reset layer fromtheme.cssunder every StyleX class. Without it the reset's* { margin: 0 }overrides every StyleX declaration.resolve.tsconfigPathslets Vite resolve the same@/imports.build.cssTargetstops Vite's CSS minifier from rewritinglight-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.
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.
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.
Add your first component. The CLI also adds the arene components and helpers it imports, and installs its npm dependencies.
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.
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:
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.
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.
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:
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.
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.