Source: https://www.hype-stack.dev/docs/getting-started/installation # Installation Three tools have to exist on your machine before anything else works: Node, pnpm, and Docker. After that it is one command, and the CLI does the rest. For the rest of the setup surface, see [Commands](/docs/development/commands) (scripts), [Onboarding](/docs/cli/onboard) (pack env walkthrough), and [Env variables](/docs/backend/env-variables) (full catalog). ## Prerequisites | Tool | Version | Why | | ----------- | ----------- | ----------------------------------------------------------------------------- | | **Node.js** | 20 or newer | Runs the backend, the frontend dev server, and the CLI. | | **pnpm** | 12 or newer | The template pins pnpm 12. npm and yarn will not resolve the workspace. | | **Docker** | Any recent | Runs Postgres, Valkey, and RustFS locally so you do not install them by hand. | The CLI checks the first two before it touches anything and stops with the fix when one is missing. Docker is only recommended: without it you skip the local databases and point `DATABASE_URL` at your own. ### Node.js Check what you have: ```bash node --version ``` If it prints anything below `v20`, install a current version. On macOS and Linux the least painful route is a version manager, because you will want to switch versions eventually: ```bash # macOS / Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 22 nvm use 22 ``` On Windows, install from [nodejs.org](https://nodejs.org) or use [nvm-windows](https://github.com/coreybutler/nvm-windows). ### pnpm pnpm 12 ships as a native binary, and older tooling trips over that. The shortest path is npm: ```bash npm install -g pnpm@12 pnpm --version ``` If you manage pnpm through Corepack, update Corepack first, because a Corepack that predates pnpm 11 looks for a file the package no longer ships: ```bash npm install -g corepack@latest corepack enable corepack prepare pnpm@12 --activate ``` **pnpm is not optional** The repo is a pnpm workspace. Running `npm install` in it will produce a broken `node_modules` and a lockfile that conflicts with everyone else's. If `pnpm --version` fails, stop here and fix that first. If your pnpm is too old to run the project's pinned version, the CLI notices and runs the install through `npx pnpm@12` for you, then tells you how to fix the toolchain properly. See [Troubleshooting](/docs/development/troubleshooting) for the exact errors. ### Docker Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) on macOS or Windows, or Docker Engine on Linux. Start it and confirm the daemon is up: ```bash docker info ``` Docker only runs Postgres, Valkey, and RustFS (S3-compatible storage) for local development. If you already have a Postgres you want to use, skip the Docker step when the CLI offers it and point `DATABASE_URL` at yours instead. ## Create the project ```bash npx @hype-stack/cli create my-app ``` The CLI asks which AI assistants your team uses and writes the agent rules in each tool's own format. Tick as many as you need. Pass `--editor cursor,claude,codex` to skip the question; the valid values are `cursor`, `t3code`, `claude`, `codex`, `copilot`, `opencode`, and `windsurf`. Then it asks for a color theme and corner radius for the frontend, and whether the admin, mobile, and extension apps should copy those settings. After the prompts, `create` does the whole first run for you: 1. Clones the template at its latest release and strips its git history. 2. Renames the workspace scope to your project name and writes `stack.json`. 3. Writes the editor rules you picked, wires the [MCP server](/docs/cli/mcp) into the project config where the editor supports it, and pulls a starter set of [agent skills](/docs/cli#agent-skills) from skills.sh. 4. Runs `pnpm install`. 5. Makes the first git commit. 6. Copies every `.env.example` to `.env`. The defaults point at the Docker containers, so the app boots as-is. 7. Asks whether to start Docker and run migrations. Say yes and it runs `docker compose up -d` in `apps/backend`, remaps any busy port, waits for Postgres, runs `prisma migrate dev` to create the tables, and mirrors the schema into the isolated test database so `pnpm test` works right away. Every answer has a flag. `--no-setup` skips step 7, `--no-skills` skips the skills, `--no-install` skips `pnpm install` (and therefore step 7 too), and `--yes` with a name skips every confirmation. See [Create a Project](/docs/cli) for the full list. ## If you said no to Docker and migrations Nothing is lost. Run the same steps yourself whenever you are ready: ```bash cd my-app/apps/backend docker compose up -d docker compose ps ``` The compose file lives in `apps/backend`, not at the repo root. It starts Postgres, Valkey, and RustFS on ports scoped to this project, so several Hype Stack projects can run side by side without colliding. Then, from the repo root, create the tables and generate the Prisma client that Kysely types its queries against: ```bash pnpm --filter @hype-stack/backend migration:create ``` ## Start everything ```bash cd my-app pnpm dev ``` | App | URL | | -------- | -------------------------------- | | Frontend | `http://localhost:4200` | | Backend | `http://localhost:3000` | | Admin | its own Vite port, printed by Nx | | Mobile | Metro QR (Expo Go) | Everything runs with hot reload. `pnpm dev` starts Metro for `apps/mobile` too. To open the app on a phone you need Expo Go from [sign.expo.dev](https://sign.expo.dev/), not the App Store. See [Mobile](/docs/mobile). For the Electron desktop build instead of the browser: ```bash pnpm --filter @hype-stack/frontend start:app ``` Same codebase, native window. ## Verify Before you move on, confirm the stack is actually healthy: 1. Open the frontend at `http://localhost:4200` and confirm it loads. 2. Hit the backend health check: `curl http://localhost:3000/ping` (or open it in a browser). 3. Run a typecheck from the repo root: ```bash pnpm typecheck ``` If those three pass, the workspace is wired correctly. ## Related setup pages | Page | When you need it | | ---------------------------------------------------- | -------------------------------------------- | | [Commands](/docs/development/commands) | Full list of pnpm / Nx scripts | | [Onboarding](/docs/cli/onboard) | Fill `.env` after installing packs | | [Env variables](/docs/backend/env-variables) | Typed catalog of backend and frontend keys | | [Mobile](/docs/mobile) | Expo Go, device testing, Metro, mobile tests | | [Troubleshooting](/docs/development/troubleshooting) | Common failures by area | ## When it does not work **`docker compose up` fails with a port already in use.** The CLI remaps busy ports when it runs Docker for you. If you ran it by hand, something else is on the Postgres, Valkey, or RustFS port. Either stop it, or change the host port in `apps/backend/docker-compose.yml`, then update `DATABASE_URL` and `VALKEY_URL` to match. **Migrations fail to connect.** The containers are probably still starting. Run `docker compose ps` in `apps/backend` and wait for the health check, then try again. **Types are wrong after a schema change.** The Prisma client is generated, not written. Re-run the migrate command, which regenerates it, or `pnpm --filter @hype-stack/backend generate`. **`pnpm dev` starts but the frontend cannot reach the API.** Check that `apps/frontend/.env` exists. Without it the frontend has no API URL and every request fails. ## Next - [Fastest Template](/docs/getting-started/fastest-template) to start from a finished app instead of the bare starter. - [Compose Your Stack](/docs/cli/add-pack) to add auth, billing, or notifications. - [Mobile](/docs/mobile) to run the Expo app on a phone or simulator. - [Commands](/docs/development/commands) for everything `pnpm dev` is doing under the hood. - [Going to production](/docs/getting-started/going-to-production) when you are ready to ship.