Skip to Content

Practical Puzzle Tutorials

Set up a theme with local fonts, build a searchable publication, persist a notebook, and protect an MFA-enabled application using Puzzle APIs.

Follow these task-oriented guides alongside the API references. Each guide includes configuration, complete TypeScript files, verification instructions, and deployment boundaries rather than another list of API methods.

Choose a workflow

TutorialWhat you will buildPrerequisites
Theme: setup and local fontsA customized light/dark theme, shared font configuration, and self-hosted Google Fonts downloaded with the CLI.React 19; npm, Bun, pnpm, or Yarn.
SEO: a searchable publicationServer-rendered home, article listing, and dynamic article pages with social metadata, a connected JSON-LD graph, and framework endpoints.React 19; Bun for the standalone example.
Storage: a persistent notebookA database-neutral notebook with MongoDB persistence, conditional CRUD, a D1 alternative, and custom-adapter integration.A MongoDB replica set; Cloudflare only for the D1 alternative.
Auth: registration to a protected dashboardPassword registration/login, required TOTP enrollment, recovery-code challenges, policy-aware route protection, session rotation, and logout, with every record stored in MongoDB. Explains each concept for newcomers.A MongoDB replica set; Bun; HTTPS.
Auth with TanStack StartThe same protected dashboard in a TanStack Start app: server routes, a server function guard, and MongoDB storage.A MongoDB replica set; Node.js; HTTPS.
Auth with Next.jsThe same protected dashboard in a Next.js App Router app: route handlers, a server component guard, and MongoDB storage.A MongoDB replica set; Node.js; HTTPS.

Theme and SEO are independent. Each Auth guide sets up its own MongoDB storage adapter; the Storage tutorial goes deeper into adapters. Use SEO's private-page guidance for authenticated routes.

API maturity

The package readiness audit records the source/export checks, executed tests, and limitations behind these labels.

  • Stable: validated API with an explicit backward-compatibility commitment. All documented React component APIs across UI, Pieces, Theme, Icons, Fullstack, and SEO are Stable, with compatibility intent within a major version. The Auth, Session, Fullstack, SEO, Storage, D1, and MongoDB APIs described in the package readiness audit are also Stable.
  • Beta: implemented and tested, but may evolve. No package or component API currently listed in the readiness audit remains Beta.
  • Experimental: insufficient validation evidence for the public surface. These tutorials do not require Experimental APIs; no documented component API currently has this classification.

Stable classifications describe API compatibility, not production readiness. Review the Auth security requirements before deploying authentication.

How to follow the examples

Code-block titles are application-relative file paths. Keep the indicated directory layout so relative imports work. Framework alternatives are alternatives, not extra metadata writers to install alongside the standalone server.

The examples target TypeScript with strict checking and React 19. Bun is an explicit runtime choice for the standalone servers and Argon2id implementation, not a requirement of the Puzzle library contracts. The TanStack Start and Next.js Auth guides run on Node.js and use @node-rs/argon2 instead.

The repository's test:tutorials check extracts the named TypeScript blocks and their JSON configuration, checks imports against built package export maps, and typechecks them together. It also runs the Theme and SEO rendering assertions and notebook behavior checks. The framework Auth guides need Next.js or TanStack Start, so the check only validates their structure, links and file paths; verify them as complete apps with the end-to-end script each guide includes. Real database conformance and framework/deployment checks are distinguished from those example checks in each tutorial.

From a repository checkout, build packages first and run the example check:

bun run build
bun run --filter '@puzzle-ui/site' test:tutorials
bun run --filter '@puzzle-ui/site' build
bun run --filter '@puzzle-ui/site' test:hydration

Set TUTORIAL_MONGODB_URI to a disposable transaction-capable MongoDB fixture to include the notebook and Auth flows. Set TUTORIAL_SITE_URL to a running local documentation build to also check rendered routes, metadata, JSON-LD, sitemap and llms.txt. These checks copy built package output into a temporary consumer project, so workspace source aliases cannot hide packaging mistakes. They remove that project afterward and never install additional dependencies. The hydration check uses the existing Playwright Chromium installation and starts/stops its own production server on an ephemeral local port. It checks fresh loads, client navigation, history and reloads for hydration errors, duplicate metadata/JSON-LD and stale route entities.

API references