Start UI [web]

Start UI [web] is an opinionated frontend starter repository from the BearStudio Team that scaffolds a new React web application with authentication, database, email tooling, and testing pre-configured through a single command.

What is Start UI [web]?

Start UI [web] is a TypeScript-based React starter template built on TanStack Start, Tailwind CSS, and shadcn/ui. Running pnpm create start-ui -t web myApp creates a new project folder containing the latest version of the starter, with Prisma for data modeling, Better Auth for authentication, and oRPC for type-safe APIs. The repository is maintained by the BearStudio Team and other contributors, and it runs on Node.js version 22 or newer with pnpm as the package manager.

What makes Start UI stand out?

• Complete stack — Node.js, TypeScript, React, TanStack Start, Tailwind CSS, shadcn/ui, React Hook Form, oRPC, Prisma, Better Auth, Storybook, Vitest, and Playwright are all wired together in one starter.
• Email development workflow — Email templates built with react-email can be previewed at http://localhost:3000/api/dev/email/{template} with optional language and props query parameters, and maildev catches outgoing emails in development on port 1080.
• OpenAPI documentation — The API exposes a live interface at http://localhost:3000/api/openapi/app where every backend endpoint can be viewed and tested directly.
• Custom icon generation — Running pnpm gen:icons turns SVG files placed in src/components/icons/svg-sources into React icon components; SVGs must be square, filled with #000, and prefixed with icon-.
• Playwright E2E tests — pnpm e2e:setup prepares an authenticated context for efficient test runs, pnpm e2e executes headless tests in CI, and pnpm e2e:ui opens an interactive runner.
• Development environment banner — Setting VITE_ENV_NAME, VITE_ENV_EMOJI, and VITE_ENV_COLOR displays a hint on non-production environments.
• Docker-based local setup — pnpm dk:init starts PostgreSQL, MinIO, and Maildev containers, while pnpm db:init pushes the Prisma schema and seeds the database.

Who is Start UI [web] for?

• Web development agencies — BearStudio built this from their client work, so agencies can reuse a consistent, battle-tested stack across projects.
• Full-stack developers — Developers who want a production-ready starting point with authentication, database, email, and testing already configured can scaffold a project in one command.
• Teams evaluating TanStack Start — The starter shows a real-world integration of TanStack Router/Query with Prisma, Better Auth, and oRPC.

What can you do with Start UI [web]?

• Agency teams: kick off new client web apps with the same stack BearStudio uses, including Storybook and Vitest for component documentation and unit tests.
• Solo developers: prototype a full-stack product with login, database schema, and email templates without setting up infrastructure from scratch.
• CI pipelines: run pnpm e2e headless after pnpm db:init to verify the whole application in continuous integration.

How do you get started with Start UI [web]?

1. pnpm create start-ui -t web myApp to scaffold the project.
2. Copy .env.example to .env and set environment variables.
3. Run pnpm install, pnpm dk:init to start Docker containers, and pnpm db:init to push the schema and seed data.
4. Start the dev server with pnpm dev.

Alternatively, if Docker is not used, point DATABASE_URL at any PostgreSQL database and run pnpm db:push and pnpm db:seed.

FAQ

How do I fix git showing many changes in my .husky folder?

Run git config --unset core.hooksPath, then rm -rf ./.husky, then pnpm install. This removes the husky hooks and lets lefthook take over correctly.

Do I need Docker to run Start UI [web]?

No. You can use any PostgreSQL database by replacing the DATABASE_URL environment variable in your .env file, then run pnpm db:push to update the schema and pnpm db:seed to seed data.

How can I preview email templates?

Start the dev server and visit http://localhost:3000/api/dev/email/{template}, where {template} is the template file name in src/emails/templates. Add ?language=fr for translations and append search params to pass props.

What is the OpenAPI endpoint?

The API documentation is available at http://localhost:3000/api/openapi/app when the dev server is running. It lists all backend routes with request and response formats and lets you test endpoints directly.

What are the requirements for custom SVG icons?

Custom icons must be placed in src/components/icons/svg-sources, be prefixed with icon-, have a square size, and be filled with #000 so the generator can replace the color with currentColor.