create-tweakui CLI

Last updated 14 November 2026
create-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.
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, runs astryx init, wires the theme in, replaces the starter's home page with Astryx's centered-hero page 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. Only tweakui-theme.css, tweakui-fonts.css, tweakui-theme.ts, the agent guide and theme in tweakui.json change (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>.tsx and an app/routes.ts entry (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

  • --dry-run runs nothing and writes nothing; it prints the commands and the diff.
  • --yes takes the defaults instead of asking. Without a terminal (CI, a coding agent) nothing is asked: pass the choices as flags.
  • --template none keeps the starter's home page and styles; --template <id> picks another Astryx template.
  • --overwrite lets add replace a page or route that has other content.
  • --fonts google links 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 (Y2K works too). npx create-tweakui themes lists 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.md at 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.md and CLAUDE.md when 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--frameworkStarter
Next.jsnextcreate-next-app
Vite + Reactvitecreate-vite
React Routerreact-routercreate-react-router
TanStack Starttanstack-startthe 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, create exits 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].

Install Tweakui

Add Tweakui to your Home Screen to open it like an app.
1. Tap Share in Safari's toolbar.
2. Choose Add to Home Screen.
3. Tap Add.