create-tweakui CLI
Last updated 14 November 2026create-tweakui puts a theme into a React app. Make the theme first in tweakui's Astryx theme lab, or start from a preset id, then pass its link or id to the CLI.Install
There's nothing to install: run it with your package manager's
create or with npx. It needs Node 22.12 or later, and the package is one file with no dependencies.Terminalnpm create tweakui@latest my-app -- --theme y2k --framework nextpnpm create tweakui@latest my-app --theme y2k --framework nextnpx create-tweakui themes
With npm, the flags of
npm create go after --; pnpm passes them straight through.Commands
create [dir](the default): asks for the component library, then runs the framework's own starter at a pinned version, installs Astryx, its CLI and the theme's fonts in one install, runsastryx init, wires the theme in, replaces the starter's home page with Astryx'scentered-heropage and makes the first commit.init: the same in a React app you already have. Outside the marked theme block, your stylesheet stays as it is.theme <source>: switches the theme. Onlytweakui-theme.css,tweakui-fonts.css,tweakui-theme.ts, the agent guide andthemeintweakui.jsonchange (and package.json, when the new theme needs fonts you don't have).add <template>: adds an Astryx template as a page (<components>/pages/<template>.tsx), installs the packages it imports and adds its route:app/<template>/page.tsx(Next.js),app/routes/<template>.tsxand anapp/routes.tsentry (React Router),src/routes/<template>.tsx(TanStack Start). Vite has no file routes, so it prints the import.themes: lists every preset id and name, by group.
Running a command again with the same inputs changes nothing ("Already up to date.").
Flags
Usagenpm create tweakui@latest [dir] -- [--framework next|vite|react-router|tanstack-start] [--theme <source>][--library astryx] [--package-manager npm|pnpm|yarn|bun][--fonts self-hosted|google][--template <id>|none] [--starter-version <version>|latest][--dry-run] [--yes]npx create-tweakui init [--theme <source>] [--fonts …] [--dry-run] [--yes]npx create-tweakui theme <source> [--fonts …] [--dry-run] [--yes]npx create-tweakui add <template> [--theme <source>] [--overwrite] [--dry-run]npx create-tweakui themesglobal: --api <origin> (default https://tweakui.app; TWEAKUI_API_URL), --cwd <dir>, --help, --version
--dry-runruns nothing and writes nothing; it prints the commands and the diff.--yestakes the defaults instead of asking. Without a terminal (CI, a coding agent) nothing is asked: pass the choices as flags.--template nonekeeps the starter's home page and styles;--template <id>picks another Astryx template.--overwriteletsaddreplace a page or route that has other content.--fonts googlelinks the theme's fonts from Google Fonts instead of installing them.
Theme sources
--theme and theme <source> take any of these:- A preset id, such as
y2k(Y2Kworks too).npx create-tweakui themeslists them; a typo gets "Did you mean y2k?". - A share link to a saved theme:
https://tweakui.app/themes/…. - A 24 h code, bare (
7KQ2M9XA) or as a link (https://tweakui.app/c/7KQ2M9XA). The editor's Code → Start a new app makes one for unsaved work; it expires after 24 hours.
tweakui.json
create and init write tweakui.json at the app root. It records the library ("library": "astryx"), the framework, where your components and stylesheet live, the theme's source and the templates you added, so later runs of theme and add know where everything goes. Its JSON Schema ships in the package as schema/tweakui.schema.json.The theme goes into a marked block at the top of your global stylesheet, between
/* tweakui:start … */ and /* tweakui:end */. Runs replace only what is between the markers; broken markers stop the run with nothing written.DESIGN.md and the project skill
create, init and theme also guide coding agents:DESIGN.mdat the app root: the theme's tokens and design taste, in the format of@google/design.md.- The skill
.agents/skills/tweakui/SKILL.md. - A pointer line to both in
AGENTS.mdandCLAUDE.mdwhen the app has them (never created), between<!-- tweakui:start -->and<!-- tweakui:end -->.
Each run rewrites both files and replaces the block. A symlinked
DESIGN.md or skill stops the run with nothing written: replace the link with the file.Frameworks and package managers
| Framework | --framework | Starter |
|---|---|---|
| Next.js | next | create-next-app |
| Vite + React | vite | create-vite |
| React Router | react-router | create-react-router |
| TanStack Start | tanstack-start | the TanStack CLI |
Package managers: npm and pnpm. yarn and bun are coming; for now
--package-manager yarn or bun installs with npm and says so.Component library
The library is Astryx (
--library astryx). shadcn/ui is coming: the question shows it as coming soon, and --library shadcn says so and exits 1. init reads the library from your package.json.Exit codes
- 0: done.
- 1: nothing written (an error). One exception: when the starter itself fails,
createexits 1 but the folder may hold what the starter wrote; delete it before you try again. - 2: done, except the manual steps it printed (a file too customised to edit gets the exact lines to add).
Releases
Each release is published to npm with provenance from the read-only mirror coolycloud/create-tweakui(opens in new tab). Its changes are in the package's CHANGELOG.md. Questions and bugs: [email protected].