🚀 Start UI [web] is an opinionated frontend starter repository created & maintained by the BearStudio Team and other contributors. It represents our team's up-to-date stack that we use when creating web apps for our clients.

Technologies

⚙️ Node.js, 🟦 TypeScript, ⚛️ React, 📦 TanStack Start, 💨 Tailwind CSS, 🧩 shadcn/ui, 📋 React Hook Form, 🔌 oRPC, 🛠 Prisma, 🔐 Better Auth, 📚 Storybook, 🧪 Vitest, 🎭 Playwright

Documentation

For detailed information on how to use this project, please refer to the documentation. The documentation contains all the necessary information on installation, usage, and some guides.

Requirements

• Node.js >= 22
• pnpm
• Docker (or a PostgreSQL database)

Getting Started

pnpm create start-ui -t web myApp

That will scaffold a new folder with the latest version of 🚀 Start UI [web] 🎉

Setup your IDE

• VS Code

cp .vscode/settings.example.json .vscode/settings.json

• Zed

cp .zed/settings.example.json .zed/settings.json

Installation

cp .env.example .env  # Setup your env variables
pnpm install          # Install dependencies
pnpm dk:init          # Start Docker containers (PostgreSQL, MinIO, Maildev)
pnpm db:init          # Push the Prisma schema and seed the database

[!NOTE] Don't want to use docker?

Setup a PostgreSQL database (locally or online) and replace the DATABASE_URL environment variable. Then you can run pnpm db:push to update your database schema and then run pnpm db:seed to seed your database.

Run

pnpm dk:start # Only if your Docker containers are not running
pnpm dev

Emails in development

Maildev to catch emails

In development, the emails will not be sent and will be caught by maildev which runs as a Docker container.

The maildev UI is available at localhost:1080 (port configurable via DOCKER_MAILDEV_UI_PORT in .env).

Preview emails

Emails templates are built with react-email components in the src/emails folder.

You can preview an email template at http://localhost:3000/api/dev/email/{template} where {template} is the name of the template file in the src/emails/templates folder.

Example: Login Code

Email translation preview

Add the language in the preview url like http://localhost:3000/api/dev/email/{template}?language={language} where {language} is the language key (en, fr, ...)

Email props preview

You can add search params to the preview url to pass as props to the template. http://localhost:3000/api/dev/email/{template}/?{propsName}={propsValue}

OpenAPI Documentation for the API

You can access the API documentation via the OpenAPI interface at:

http://localhost:3000/api/openapi/app

This interface allows you to:

• View complete and up-to-date documentation of all backend endpoints exposed by the API.

• Understand request and response formats for each route.

• Facilitate development and debugging by testing endpoints directly from the interface, without needing the frontend.

Generate custom icons components from svg files

Put the custom svg files into the src/components/icons/svg-sources folder and then run the following command:

pnpm gen:icons

If you want to use the same set of custom duotone icons that Start UI is already using, checkout Phosphor

[!WARNING] All svg icons should be svg files prefixed by icon- (example: icon-external-link) with square size and filled with #000 color (will be replaced by currentColor).

E2E Tests

E2E tests are setup with Playwright.

pnpm e2e:setup  # Setup context to be used across test for more efficient execution 
pnpm e2e        # Run tests in headless mode, this is the command executed in CI
pnpm e2e:ui     # Open a UI which allows you to run specific tests and see test execution

[!WARNING] The generated e2e context files contain authentication logic. If you make changes to your local database instance, you should re-run pnpm e2e:setup. It will be run automatically in a CI context.

Production

pnpm install
pnpm storybook:build # Optional: Will expose the Storybook at `/storybook`
pnpm build
pnpm start

Show hint on development environments

Setup the VITE_ENV_NAME env variable with the name of the environment.

VITE_ENV_NAME="staging"
VITE_ENV_EMOJI="🔬"
VITE_ENV_COLOR="teal"

FAQ

git detect a lot of changes inside my .husky folder

You probably have updated your branch with lefthook installed instead of husky. Follow these steps to fix your hooks issue:

• git config --unset core.hooksPath
• rm -rf ./.husky
• pnpm install

From now husky should have been removed; and lefthook should run your hooks correctly.