Skip to Content

Create

Generate a React application with Puzzle UI, framework-aware theme setup, and optional Tailwind CSS and Puzzle Auth with a working database.

@puzzle-ui/create is an interactive command-line generator for new Puzzle applications. It scaffolds a project, configures the Puzzle theme for your framework's router, and can add Tailwind CSS and Puzzle Auth backed by MongoDB or Cloudflare D1. For a guided walkthrough, see Create a Project.

Install

The package is a CLI; run it with your package manager rather than adding it as a project dependency.

npx @puzzle-ui/create

Yarn's dlx command requires Yarn 2 or later; with Yarn Classic, use npx @puzzle-ui/create. The CLI requires Node.js 20.19 or later, one of npm, Bun, pnpm, or Yarn, and an internet connection to fetch framework templates and dependencies.

Quick start

Run the generator, answer the prompts, then change into the generated directory and start the dev server. The remaining sections describe the available choices and generated files.

Interactive setup

The CLI asks the following questions. It has no command-line flags; setup is configured through these prompts.

PromptTypeDefaultDescription
Project nameTextNone (placeholder: my-awesome-app)Required; converted to kebab-case for the directory and package name.
FrameworkSelectionNoneChoose Next.js, TanStack Start, React Router, or Basic React.
Install Tailwind CSS?ConfirmationYesOptionally add Tailwind CSS v4 and its framework integration.
Add Puzzle Auth?ConfirmationNoOptionally add the Puzzle Auth client and, for full-stack frameworks, server integration.
DatabaseSelectionMongoDBFull-stack frameworks with Auth only. Choose MongoDB, Cloudflare D1, or a custom database.
First application user emailTextNoneMongoDB and D1 only. Creates the first local application sign-in account.
First application user passwordMasked passwordNoneMongoDB and D1 only. Requires 12–1024 characters and at most 4096 UTF-8 bytes.
Confirm passwordMasked passwordNoneMust match the supplied password.

Canceling a prompt cancels project creation. The CLI refuses to create a project if the target directory already exists; it does not overwrite existing files.

Frameworks and generated structure

Next.js, TanStack Start, and React Router (framework mode) projects are generated with their respective official CLIs. Basic React is generated by Puzzle using React 19, Vite, and TypeScript. The framework generator may supply additional files; the paths below are the Puzzle-specific starter files and configuration.

SelectionStarter files and configuration
Next.js — Next.js App Routersrc/app/providers.tsx, src/app/layout.tsx, src/app/page.tsx, and next.config.ts. The providers apply Theme with system color mode and map Puzzle Link and Image to next/link and next/image.
TanStack Start — full-stack Reactsrc/routes/__root.tsx, src/routes/index.tsx, and vite.config.ts. The root route applies Theme and maps Puzzle Link to the TanStack Router Link. Unless the project uses D1, the CLI adds Nitro for a deployable Node.js server, a start script, and font cache headers.
React Router — framework modeapp/root.tsx, app/routes.ts, app/routes/home.tsx, app/app.css, and vite.config.ts. The root layout applies Theme and maps Puzzle Link to the React Router Link. The template's welcome screen is replaced.
Basic React — React + Vite + TypeScriptindex.html, src/main.tsx, src/App.tsx, src/index.css, vite.config.ts, and tsconfig.json with app and node configs. The entry point applies Theme.

Every starter home page links to the documentation of the Puzzle packages the project uses, so you can jump straight to the relevant guides. Because the framework Link is registered through the theme's component mapping, Puzzle Link performs client-side navigation for internal routes.

The CLI updates the generated package.json name, configures framework package transpilation where needed, and installs @puzzle-ui/ui and @puzzle-ui/theme using the detected package manager. It detects npm, Bun, pnpm, or Yarn from the package-manager environment; if detection is unavailable, it uses npm.

Fonts

Every project serves its fonts locally. The CLI writes a default puzzle-fonts.json that uses Geist for headings and body text, passes it to Theme with fontSource="local", adds a fonts:download script, and downloads the Latin and Latin Extended subsets into public/fonts.

FrameworkFont configuration
Next.js, TanStack Start, Basic Reactsrc/puzzle-fonts.json
React Routerapp/puzzle-fonts.json

Edit the configuration to change fonts, then run npm run fonts:download and commit public/fonts. See the Theme CLI for the configuration format and Deployment for caching.

Tailwind CSS

Tailwind is enabled by default, but you can opt out. When enabled, the generator installs Tailwind CSS v4 as a development dependency and configures the integration:

FrameworkConfiguration
Next.jsAdds @import "tailwindcss"; to src/app/globals.css and configures postcss.config.mjs with @tailwindcss/postcss.
TanStack StartAdds the Tailwind import to the stylesheet used by the root route, configures the @tailwindcss/vite plugin, and preserves the Puzzle packages in the SSR noExternal configuration.
React RouterAdds the Tailwind import to app/app.css and configures the @tailwindcss/vite plugin.
Basic ReactAdds the Tailwind import to src/index.css and configures the @tailwindcss/vite plugin.

The CLI installs tailwindcss, @tailwindcss/postcss, and postcss for Next.js; for the Vite-based frameworks it installs tailwindcss and @tailwindcss/vite. React Router's template ships with Tailwind, so the CLI removes it when you opt out.

Puzzle Auth

Puzzle Auth is off by default. When enabled, the CLI installs @puzzle-ui/auth, @puzzle-ui/fullstack, and @puzzle-ui/session, adds an AuthProvider with the /api/auth base path, and creates sign-in and sign-up views using AuthExperience.

Databases

For Next.js, TanStack Start, and React Router, the CLI asks which database stores users, sessions, and rate-limit counters:

DatabaseGenerated setup
MongoDBInstalls @puzzle-ui/storage-mongodb, the mongodb driver, and @node-rs/argon2. Adds a docker-compose.yml that runs a single-node MongoDB replica set (required for transactions) with access control, a keyfile, and a port bound to 127.0.0.1. Randomly generated administrator and application passwords are written to .env, which docker compose reads; the application user can only read and write the project database. Run npm run db:setup (or your selected package manager) before dev to start the database, initialize missing users, and verify authenticated primary readiness.
Cloudflare D1Installs @puzzle-ui/storage-d1, hashes passwords with the built-in Pbkdf2PasswordHasher and a generated AUTH_PASSWORD_PEPPER_HEX, adds wrangler.jsonc with a DB binding, and wires the Cloudflare runtime: OpenNext for Next.js, and @cloudflare/vite-plugin for TanStack Start and React Router. dev uses a local D1 database; preview, deploy, and cf-typegen scripts are added.
CustomInstalls @puzzle-ui/storage and leaves a documented placeholder in the database module. Until it returns a storage adapter, the auth API responds with HTTP 503.

The CLI writes a .env file with the database settings, an APP_ORIGIN for CSRF checks, and freshly generated AUTH_ENCRYPTION_KEY_HEX and AUTH_RATE_LIMIT_SECRET secrets (plus AUTH_PASSWORD_PEPPER_HEX for D1, and database passwords for MongoDB). .env is added to .gitignore; never commit it, and set new values in your deployment environment as described in Deployment.

For MongoDB and D1, the CLI automatically initializes the local database and registers the first application account after installing dependencies. MongoDB requires Docker with Compose to be running. D1 uses the persisted local database used by dev, not your remote Cloudflare database. The password is sent through stdin to the generated seed script and stored only as an Auth password hash, never in project files or command-line arguments. Sign in at /sign-in when development starts. Puzzle Auth has no built-in administrator roles; this account has normal application permissions. MongoDB administrator credentials remain separate and randomly generated. Repeating bootstrap for an existing email fails rather than resetting its password.

Deploying to Cloudflare

Before the first deploy, run wrangler d1 create <name> and copy the database ID into wrangler.jsonc, then store the secrets with wrangler secret put. Keep AUTH_PASSWORD_PEPPER_HEX stable: changing it makes every existing password stop verifying.

Routes

Full-stack projects are ready to sign up, sign in, and sign out:

RoutePurpose
/sign-up, /sign-inAuthExperience views that navigate to /dashboard after authentication.
/dashboardA protected route with MFA settings. It resolves the session on the server and redirects to /sign-in when no user is signed in.
/api/auth/*The Puzzle Auth API, restricted to the endpoints the generated UI uses.
FrameworkAuth files
Next.jssrc/app/{sign-in,sign-up,dashboard}/page.tsx, src/app/api/auth/[...auth]/route.ts, src/components/sign-out-button.tsx, and server modules under src/lib/auth/.
TanStack Startsrc/routes/{sign-in,sign-up,dashboard}.tsx, src/routes/api/auth/$.ts, src/components/sign-out-button.tsx, and server modules under src/lib/auth/.
React Routerapp/routes/{sign-in,sign-up,dashboard}.tsx, app/routes/api.auth.ts, app/components/sign-out-button.tsx, and .server.ts modules under app/lib/auth/.
Basic Reactsrc/auth/sign-in.tsx and src/auth/sign-up.tsx. Basic React has no server runtime or API route; host the authentication API separately and configure the client base path for it.

The server modules read the environment, create the storage adapter and password hasher, and build the AuthServer with sessions, rate limiting, MFA, and CSRF protection. Review them against the Authentication setup guide before going to production, in particular the trusted client IP header for your host.

To use a passkey, first sign in with your password and register it in the dashboard's MFA settings. Save the recovery codes shown at enrollment. Passkeys are bound to APP_ORIGIN and its hostname, so configure the exact deployed HTTPS origin before registering production passkeys.

Run your application

After generation and dependency installation complete, run the development script in the new project directory with the selected package manager. For example:

cd my-awesome-app
npm run dev

With Auth and MongoDB, run npm run db:setup before npm run dev, using your selected package manager. Setup can initialize an older local volume that has no users and create a missing application user when the administrator credentials match. It never resets existing passwords or deletes data. If authentication still fails, restore the original .env credentials or update the user password as an administrator; also check exported shell variables, which override Compose's .env values. Then open /dashboard to try the protected route.

To go to production, follow Deployment for your framework and database.

CLI package details

The package requires Node.js >=20.19.0 and publishes one executable, create-puzzle, at ./dist/index.js. It does not expose a JavaScript import API or package subpaths. The executable takes no flags; it always starts the interactive setup.