npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@puzzle-ui/create

v0.12.0

Published

CLI for scaffolding Puzzle React applications with Next.js, TanStack Start, or Vite.

Readme

@puzzle-ui/create

Generate a new React application with Puzzle UI and Theme configured. Choose Next.js, TanStack Start, React Router, or Basic React (React + Vite + TypeScript), then optionally add Tailwind CSS v4 or Puzzle Auth with a MongoDB or Cloudflare D1 database.

Documentation: https://puzzle-ui.com/docs/create

Requirements

  • Node.js 20.19 or later
  • npm, Bun, pnpm, or Yarn
  • Internet access to download the framework template and dependencies
  • Docker with Compose when selecting MongoDB with Auth

Create a project

Run the interactive generator; it prompts for a project name, framework, Tailwind, Puzzle Auth, and (for full-stack Auth) a database. The name is converted to kebab-case. The CLI does not overwrite an existing directory and has no command-line flags.

Selecting MongoDB or D1 also prompts for the first application user's email, a masked password (12–1024 characters), and password confirmation. After installing dependencies, the CLI automatically initializes the local database and registers that account using Puzzle Auth's password hashing. MongoDB starts through Docker Compose; D1 uses the same local persisted database as development. Credentials go to the seed process over stdin, not command-line arguments or project files. Puzzle Auth currently has no administrator roles, so this is a normal sign-in account, not a privileged application administrator. MongoDB's database administrator credentials remain separate and randomly generated. Custom databases and Basic React do not prompt for an account.

Existing project directories are never overwritten. If you remove a project directory and scaffold it again with the same Compose project name, its MongoDB volumes can still contain the previous database. Before installing dependencies, the CLI detects these volumes and asks whether to permanently delete their data and accounts and start fresh. The default is No: declining or cancelling stops creation and preserves the volumes, leaving the generated project files in place. Only this project's mongodb-data and mongodb-config volumes are eligible; volumes used by another service or project are refused. A normal db:setup never resets existing data or passwords.

Generated MongoDB and D1 sign-in pages enable AuthExperience's offerPasskeyAfterSignIn option. After a successful login, users without a passkey can add one before navigating to the dashboard, or skip the step. Enrollment requires the current password, and new recovery codes are shown before continuing. Unsupported browsers and accounts with an existing passkey continue directly; sign-up is unchanged.

npx @puzzle-ui/create

Alternatives: bunx @puzzle-ui/create, pnpm dlx @puzzle-ui/create, or yarn dlx @puzzle-ui/create (Yarn 2+; Yarn Classic users can use npx).

The generator installs @puzzle-ui/ui and @puzzle-ui/theme, maps Puzzle Link (and Image on Next.js) to the framework's components in the theme, adds a starter page that links to the package docs, and uses the detected package manager for framework generation and dependency installation. Tailwind is enabled by default; Puzzle Auth is optional and disabled by default.

When Auth is enabled, the CLI adds client auth components and, for full-stack frameworks, sign-in and sign-up pages, a protected /dashboard route, an API route, and server modules wired to the chosen database. MongoDB projects get a docker-compose.yml with access control; its administrator and least-privileged application passwords are randomly generated into .env, which docker compose reads. Run bun run db:setup (or your selected package manager) before dev. It starts the replica set, checks both accounts and primary readiness, and can initialize missing users on older local volumes without users. It never resets existing passwords or deletes data. If credentials do not match an existing volume, restore its original .env or update the user password as an administrator; exported shell variables also override Compose's .env. D1 projects get wrangler.jsonc and the Cloudflare runtime integration. A .env with preview database settings and generated secrets is written for local development. A custom database leaves a storage adapter placeholder. Review the server setup against the Authentication setup guide before production.

After signing in with a password, register a passkey in the dashboard's MFA settings before using it to sign in. Save the recovery codes shown at enrollment. Passkeys are bound to the exact APP_ORIGIN and its hostname; use HTTPS in production and update APP_ORIGIN for your deployed host.

Every project serves its fonts locally: the CLI writes a default puzzle-fonts.json, passes it to Theme, and downloads the fonts into public/fonts. Run fonts:download after changing the configuration. TanStack Start projects that do not use D1 include Nitro for a Node.js server with font cache headers.

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

See the Create documentation for framework-specific generated files, Tailwind setup, and Auth requirements.

Review generated applications against your deployment, security, and accessibility requirements before release.

End-to-end tests

Contributors can verify every project shape the CLI generates with the end-to-end suite:

bun run test:e2e

The suite builds the workspace and packs the local @puzzle-ui/* packages. It then creates 28 projects in a temporary directory: each framework, with and without Tailwind, and each Auth and database option. Every project is installed with Bun, using the packed packages instead of published versions. Each project then:

  • downloads its local fonts
  • checks the generated .env, Docker Compose and Wrangler files
  • runs the generated bun run dev command and checks the home route and Auth API
  • builds and typechecks
  • serves the production build

MongoDB projects run db:setup and confirm that the database rejects unauthenticated access. A legacy-volume regression verifies data-preserving user initialization, repeated setup, missing application-user recovery, and refusal to reset mismatched administrator or application passwords. MongoDB and D1 projects exercise registration, sessions, sign-out and protected dashboards in development, then sign-up, sign-out, sign-in, cross-site request rejection and protected dashboards in production. TanStack Start projects check their not-found page; Nitro projects also verify the font cache headers. The temporary directory, containers and volumes are removed when the suite finishes.

MongoDB and D1 variants also sign in with the account created during scaffolding in both development and production, verify that rerunning bootstrap cannot overwrite its password, exercise passwords with quotes, shell metacharacters, and Unicode, and test passkey registration and sign-in. TanStack Start with MongoDB additionally exercises passkeys in Chromium with a virtual authenticator.

React Router + D1 projects load reflect-metadata in the Worker entry before importing the server build. Keep this import: WebAuthn's certificate dependencies require the polyfill before they are evaluated in production.

Requirements: Bun, Node.js, Docker with Compose, Playwright Chromium (bunx playwright install chromium; on Linux, use bunx playwright install --with-deps chromium to also install system dependencies), and network access to npm and Google Fonts. The Create E2E workflow installs Chromium and its system dependencies before running the suite. The suite uses ports 4310–4377 and 27110–27177 on the host.

| Variable | Purpose | | --- | --- | | PUZZLE_E2E_FILTER | Comma-separated substrings of scaffold IDs to run, for example tanstack-auth-d1,next-no-auth. | | PUZZLE_E2E_CONCURRENCY | Number of test files (frameworks) to run in parallel. Defaults to 4. | | PUZZLE_E2E_SKIP_BUILD | Set to 1 to reuse existing package builds. | | PUZZLE_E2E_KEEP | Set to 1 to keep generated projects and MongoDB containers for debugging. |

Package details

The published command is create-puzzle. The package is CLI-only; it does not provide an importable JavaScript API. License: MIT.