🚀 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
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
cp .vscode/settings.example.json .vscode/settings.json
cp .zed/settings.example.json .zed/settings.json
TypeScript 7
This project uses TypeScript 7, the native compiler. It ships a tsc binary but no tsserver, so editors need the native language server to typecheck exactly like pnpm lint:ts does.
- VS Code: install the TypeScript 7 extension (
TypeScriptTeam.native-preview). The example settings already enable it:
"js/ts.experimental.useTsgo": true,
"js/ts.tsdk.path": "./node_modules/typescript"
Without it, your editor falls back to its bundled TypeScript 5 and may report different errors than CI.
Installation
cp .env.example .env # Setup your env variables
pnpm install # Install dependencies
pnpm dk:init # Start Docker containers (PostgreSQL, S3-compatible storage, 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
Docker image
The Dockerfile builds a production image of the app. It is based on the
official pnpm image, which
also installs the Node runtime. The Node major version is pinned by the
NODE_VERSION build argument (default 24).
Only the VITE_* variables are needed at build time, because they are inlined
in the client bundle. Server variables (DATABASE_URL, AUTH_SECRET, EMAIL_*,
S3_*...) are not build arguments: they are read at runtime from the
container environment, so they never end up in the image layers.
Build the image:
docker build -t start-ui-web \
--build-arg VITE_BASE_URL="http://localhost:3000" \
--build-arg VITE_S3_BUCKET_PUBLIC_URL="http://localhost:7070/default" \
--build-arg VITE_ENV_NAME="DOCKER" \
--build-arg VITE_ENV_EMOJI="🐋" \
--build-arg VITE_ENV_COLOR="blue" \
.
Run it, passing the server variables. With the local Docker Compose stack
running (pnpm dk:start), the container can reach the services through the
compose network using their service names (postgres, s3, maildev):
docker run -d --name start-ui-web -p 3000:3000 \
--network start-ui-web_default \
-e DATABASE_URL="postgres://startui:startui@postgres:5432/startui" \
-e AUTH_SECRET="change-me" \
-e EMAIL_SERVER="smtp://username:password@maildev:1025" \
-e EMAIL_FROM="Start UI <[email protected]>" \
-e S3_HOST="s3:7070" \
-e S3_ACCESS_KEY_ID="startui-access-key" \
-e S3_SECRET_ACCESS_KEY="startui-secret-key" \
-e S3_SECURE=false \
-e S3_FORCE_PATH_STYLE=true \
start-ui-web
[!NOTE]
The start-ui-web_default network is created by Docker Compose. Outside of
the compose stack, omit --network and point the variables at your own
services. You can also use --env-file instead of individual -e flags.
The container runs as the unprivileged node user, listens on port 3000
and exposes a Docker HEALTHCHECK.
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.
Run the react-email preview server (port 3030, or the next free one, separate from the Vite app on 3000):
pnpm dev:email
Open http://localhost:3030 to browse templates under src/emails/templates. Each template should define PreviewProps on the default export for realistic fixtures, including language (no default is injected), OTP code, and so on. Use the preview toolbar Props tab to tweak props live, for example to switch language, without changing the template source.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
