start-ui-web
<h1 align="center"><img src=".github/assets/thumbnail.png" alt="Start UI Web" /></h1> 🚀 Start UI <small>[web]</small> is an opinionated frontend starter repository created & maintained by the [BearStudio Team](https://www.bearstudio.fr/team) and other contributors. It represents our team's up-to-date stack that we use when creating web apps for our clients. ## Technologies <div align="center" style="margin: 0 0 16px 0"><img src=".github/assets/tech-logos.png" alt="Technologies logos of the starter" /></div> [⚙️ Node.js](https://nodejs.org), [🟦 TypeScript](https://www.typescriptlang.org/), [⚛️ React](https://react.dev/), [📦 TanStack Start](https://tanstack.com/start), [💨 Tailwind CSS](https://tailwindcss.com/), [🧩 shadcn/ui](https://ui.shadcn.com/), [📋 React Hook Form](https://react-hook-form.com/), [🔌 oRPC](https://orpc.unnoq.com/), [🛠 Prisma](https://www.prisma.io/), [🔐 Better Auth](https://www.better-auth.com/), [📚 Storybook](https://storybook.js.org/), [🧪 Vitest](https://vitest.dev/), [🎭 Playwright](https://playwright.dev/) ## Documentation For detailed information on how to use this project, please refer to the [documentation](https://docs.web.start-ui.com). The documentation contains all the necessary information on installation, usage, and some guides. ## Requirements * [Node.js](https://nodejs.org) >= 22 * [pnpm](https://pnpm.io/) * [Docker](https://www.docker.com/) (or a [PostgreSQL](https://www.postgresql.org/) database) ## Getting Started ```bash pnpm create start-ui -t web myApp ``` That will scaffold a new folder with the latest version of 🚀 Start UI <small>[web]</small> 🎉 ## Setup your IDE - VS Code ```bash cp .vscode/settings.example.json .vscode/settings.json ``` - Zed ```bash cp .zed/settings.example.json .zed/settings.json ``` ## Installation ```bash 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 ```bash 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](https://github.com/maildev/maildev) which runs as a Docker container. The maildev UI is available at [localhost:1080](http://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](http://localhost:3000/api/dev/email/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: ```bash pnpm gen:icons ``` If you want to use the same set of custom duotone icons that Start UI is already using, checkout [Phosphor](https://phosphoricons.com/) > [!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. ```sh 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 ```bash 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 <details><summary><strong>git detect a lot of changes inside my <code>.husky</code> folder</strong></summary> <p> You probably have updated your branch with lefthook installed instead of husky. Follow these steps to fix your hooks issue: <ul> <li><code>git config --unset core.hooksPath</code></li> <li><code>rm -rf ./.husky</code></li> <li><code>pnpm install</code></li> </ul> From now husky should have been removed; and lefthook should run your hooks correctly. </p> </details>