Create a Project

The @puzzle-ui/create package creates a new React application with Puzzle UI installed and configured.

It supports Next.js, TanStack Start, and a basic React + Vite application.

RequirementsCopy Anchor Link

• Node.js 20.19 or later.
• npm, Bun, pnpm, or Yarn.
• An internet connection to download framework templates and dependencies.

Run the generatorCopy Anchor Link

npmCopy Anchor Link

npx @puzzle-ui/create

BunCopy Anchor Link

bunx @puzzle-ui/create

pnpmCopy Anchor Link

pnpm dlx @puzzle-ui/create

YarnCopy Anchor Link

yarn dlx @puzzle-ui/create

Yarn's dlx command requires Yarn 2 or later. With Yarn Classic, use the npm command.

Interactive setupCopy Anchor Link

The generator asks for four options.

Project nameCopy Anchor Link

Enter a project name. The generator converts it to kebab-case and uses it for the target directory and package name.

FrameworkCopy Anchor Link

Next.js and TanStack Start projects are generated using their official CLI tools. The Basic React template is generated directly by Puzzle.

Tailwind CSSCopy Anchor Link

You can optionally configure Tailwind CSS v4.

When enabled, the generator configures the appropriate integration for the selected framework and installs the required development dependencies.

Puzzle AuthCopy Anchor Link

You can optionally add Puzzle authentication.

When enabled, the generator installs:

• @puzzle-ui/auth
• @puzzle-ui/fullstack
• @puzzle-ui/session

For Next.js and TanStack Start, it also creates:

• An application-level AuthProvider.
• A sign-in page.
• A sign-up page.
• A framework-specific authentication API route.
• A server-only AuthServer registration module.
• An application bootstrap function.

For Basic React, it creates the AuthProvider and sign-in/sign-up components. A Basic React application has no server runtime, so its authentication API must be hosted separately.

See Authentication Setup for the required server configuration.

What gets configuredCopy Anchor Link

After framework generation, the CLI:

1. Configures framework package transpilation.
2. Adds the Puzzle theme provider.
3. Creates a starter page using the Puzzle UI package.
4. Sets the generated package name.
5. Optionally configures and installs Tailwind CSS.
6. Optionally creates the Puzzle Auth client and server integration files.
7. Installs the selected Puzzle packages.

The target directory must not already exist. The generator never overwrites an existing project.

Start developingCopy Anchor Link

Move into the generated directory and run its development server.

cd my-dashboard
npm run dev

Use the package manager selected during setup. For example:

cd my-dashboard
bun run dev

Manual installationCopy Anchor Link

Install the UI and theme packages:

npm install @puzzle-ui/ui @puzzle-ui/theme

Add the theme provider at the root of your application.

import { Theme } from "@puzzle-ui/theme";
import { Button } from "@puzzle-ui/ui";

const App = () => (
  <Theme theme="system">
    <main>
      <h1>My application</h1>
      <Button>Continue</Button>
    </main>
  </Theme>
);

export default App;

To add the authentication packages:

npm install @puzzle-ui/auth @puzzle-ui/fullstack @puzzle-ui/session

Follow Authentication Setup before exposing authentication routes.

TroubleshootingCopy Anchor Link

The project directory already existsCopy Anchor Link

Choose a different project name or remove the existing directory yourself. The generator deliberately refuses to overwrite existing files.

Framework generation failsCopy Anchor Link

The generator downloads the framework CLI through your selected package manager. Verify that the package manager is installed and can access the package registry.

Dependency installation failsCopy Anchor Link

Run the failed installation command manually from the generated project directory. Check the package manager output for registry, network, or version errors.

Authentication returns HTTP 503Copy Anchor Link

The server bootstrap is intentionally incomplete. Configure the storage adapter, password hasher, rate limiter, session manager, MFA manager, step-up manager, cookies, CSRF policy, and trusted client IP resolver.

Register the resulting AuthServer with configureAuthServer.

Tailwind styles are missingCopy Anchor Link

Check that Tailwind was enabled during setup and that the generated CSS entry point is imported by the application.

Package detailsCopy Anchor Link

The generator is published as @puzzle-ui/create. Its executable is named create-puzzle.

The package requires Node.js 20.19 or later.