Pre-alphaThe registry and the CLI are not published yet.Roadmap

CLI

Initialize a project and add components with the axiom CLI.

Not published yet

npx axiom doesn’t work yet: the CLI isn’t on npm. This page is the specification it is being built against, so commands and options may still change.

The CLI copies source files into your project. It is the only thing Axiom publishes, and it never becomes a runtime dependency of your app: once the files are copied, your app doesn’t need it.

init

npx axiom init
pnpm dlx axiom init
yarn dlx axiom init
bun x axiom init

Sets up a project for Axiom:

  1. Asks for the styling tool: stylesheet, unistyles, nativewind or uniwind. Only the ones the registry has a variant for are offered.
  2. Checks that tsconfig.json resolves the aliases, and offers to add the missing paths entries (see Aliases).
  3. Copies the foundations (theme, tokens, light / dark) and the headless core.
  4. Asks, then installs the styling dependency and what the copied files need.
  5. Writes axiom.json, with everything it copied listed in items.

Nothing is copied before step 2 passes: a project with half its aliases resolved is worse than one with none.

OptionWhat it does
--styling <tool>Answers the styling question, for a script or a CI job.
--installInstalls without asking.
--no-installPrints the install command instead of running it.
--forceSets up a project that already has an axiom.json. Existing files are kept.

Aliases

Components are imported through an alias, so init resolves each one through the paths of your tsconfig.json before copying anything. When an alias doesn’t resolve, it shows the entry it would add:

Terminal
tsconfig.json doesn't resolve @/theme, @/components/core, @/hooks, @/components/ui, @/components/compositions, @/components/blocks.
Add "@/*": ["./src/*"] to its "compilerOptions.paths"? [Y]es [n]o

Answer n, or keep a tsconfig.json the CLI can’t rewrite safely — one with comments — and it asks for aliases your project already resolves instead.

Installing

Before installing anything, init and add list the packages and ask. Answer yes and the CLI says what it is installing, with the command it runs:

Terminal
Install react-native-reanimated, react-native-gesture-handler? npx expo install react-native-reanimated react-native-gesture-handler
◇ Installing react-native-reanimated, react-native-gesture-handler
  npx expo install react-native-reanimated react-native-gesture-handler

Answer no and it prints the command instead. --install skips the question, --no-install answers no. Without a terminal to ask, init installs and add prints the command.

The CLI uses the package manager of your project, from its lockfile, and goes through expo install when the project has Expo, so the versions match your SDK.

add

npx axiom add bottom-sheet
pnpm dlx axiom add bottom-sheet
yarn dlx axiom add bottom-sheet
bun x axiom add bottom-sheet

Adds a component to your project. The CLI:

  • copies the variant that matches your configured styling;
  • copies missing internal dependencies (portal, overlay, tappable…);
  • installs third-party packages such as Reanimated or Gesture Handler;
  • never overwrites an existing file without asking (see Existing files);
  • registers the component’s tokens in the theme, if it has any (see Component tokens);
  • adds the component and every internal dependency it copied to items in axiom.json.

Internal dependencies are resolved as a graph. Adding bottom-sheet also brings in what it relies on, and skips anything already in your project:

     bottom-sheet
          │
     ┌────┴────┐
     ↓         ↓
  portal    overlay

Names are plain component names. A component that is one file stays one file; one that brings a hook or a subcomponent gets a folder with an index.ts:

npx axiom add button         # → components/ui/button.tsx
npx axiom add bottom-sheet   # → components/ui/bottom-sheet/
pnpm dlx axiom add button         # → components/ui/button.tsx
pnpm dlx axiom add bottom-sheet   # → components/ui/bottom-sheet/
yarn dlx axiom add button         # → components/ui/button.tsx
yarn dlx axiom add bottom-sheet   # → components/ui/bottom-sheet/
bun x axiom add button         # → components/ui/button.tsx
bun x axiom add bottom-sheet   # → components/ui/bottom-sheet/
components/ui
button.tsx
bottom-sheet
bottom-sheet.tsx
bottom-sheet-root.tsx
use-bottom-sheet.ts
index.ts# so "@/components/ui/bottom-sheet" resolves here

Either way you import it the same: import { BottomSheet } from "@/components/ui/bottom-sheet". Its tokens go to theme/components/, not here.

Existing files

Copied files belong to your project, so add protects your changes. A file identical to the registry is skipped silently. When a file differs:

FileWhat happens
A file of the component you namedThe CLI asks, per file: keep yours, overwrite it, overwrite all of the remaining ones, or keep all of yours.
A file of an internal dependency already in your projectKept. add button never touches your tappable.tsx. Name the dependency to update it: add tappable.
A file your project owns once created, like the icon registryKept, always.
npx axiom add button --overwrite
pnpm dlx axiom add button --overwrite
yarn dlx axiom add button --overwrite
bun x axiom add button --overwrite

--overwrite replaces the files of the components you named without asking. Dependencies and owned files are still kept, and theme files (theme/, including each component’s tokens) are still asked about, since that is where you customize them. Without a terminal to ask in, they are kept.

Icons

The first item that needs icons asks where they come from (expo-symbols or custom) and saves the answer as icons. Pass --icons <source> to answer without a prompt. When a component draws icons your registry doesn’t have, add lists them. See Icon.

The first item that depends on the navigation library, like use-overlay-back-handler, detects it from package.json (expo-router, react-navigation or react-native without one) and saves it as navigation. Pass --navigation <library> to override the detection.

Without a terminal (CI, a script), nobody can answer: differing files are kept and the CLI lists them.

Standalone

npx axiom add tab --standalone
pnpm dlx axiom add tab --standalone
yarn dlx axiom add tab --standalone
bun x axiom add tab --standalone

For an app that already has its own design system and wants one component from the catalog. --standalone writes a single file that imports only React, React Native and the npm packages the component uses:

  • the Axiom pieces it stands on (Tappable, Text, Icon, its hooks) are inlined;
  • useTheme() is gone. The file declares a theme constant with the values of the light theme it reads, and each component’s tokens are typed as in the registry;
  • nothing else is copied, and axiom.json is neither needed nor written.

The component no longer follows a theme: light / dark and any restyling are yours to handle, in a file that is already yours. What Axiom still guarantees is the behavior: touch targets, gestures, states, safe areas, accessibility.

The file goes where its layer’s alias resolves in tsconfig.json: @/components/ui/tab.tsx for a primitive. Without an axiom.json, pass --styling (stylesheet, unistyles, nativewind or uniwind), or answer the prompt. NativeWind and Uniwind get the same file, with cx inlined next to the components that join class names. A component that draws icons carries its own icon registry, the icons object in the file, filled from the source you pick; add your icons there.

Components that render through a portal (Dialog, Menu, Bottom Sheet, Toast, Snackbar) aren’t available standalone yet: a portal needs a host mounted at the root of the app.

sync

npx axiom sync
pnpm dlx axiom sync
yarn dlx axiom sync
bun x axiom sync

Brings your project in line with items in axiom.json. Use it to set up a project with the same items as another one, to restore files that were deleted, or to update what you copied. It needs an axiom.json.

For each item, sync runs the same steps as add: it copies the variant for your styling, resolves internal dependencies, and installs missing npm packages. Files missing from your project are written. Then, when files differ from the registry, it asks two questions:

  1. Which levels you keep as they are. All of them are checked by default, so pressing Enter overwrites nothing.
  2. Which differing files of the other levels to overwrite. All of them are checked by default.
LevelWhat it covers
coreThe core primitives and the hooks
themeThe theme folder: tokens, and each component’s tokens
componentsPrimitives, compositions and blocks

Files your project owns once created, like the icon registry, are never overwritten.

Two options answer the questions for you:

npx axiom sync --keep core,theme --overwrite
pnpm dlx axiom sync --keep core,theme --overwrite
yarn dlx axiom sync --keep core,theme --overwrite
bun x axiom sync --keep core,theme --overwrite
  • --keep takes the levels to keep, separated by commas, or none.
  • --overwrite replaces every differing file of the other levels without asking which.

Without a terminal to ask in, what no option decides is kept: sync alone only writes missing files, and --keep without --overwrite lists the files it left alone.

A component you update can rely on a token or a core primitive newer than the one you kept. Typecheck after a partial update.

Configuration

The CLI reads and writes axiom.json at the root of your project: styling variant, aliases, and the list of copied items. See Configuration.