Quick Start
Get the ITU monorepo running locally.
Prerequisites
Before you begin, make sure the following tools are installed on your machine.
| Tool | Version | Purpose | Install |
|---|---|---|---|
| Node.js | 20+ | JavaScript runtime for all apps and packages | https://nodejs.org |
| pnpm | 9+ | Fast, disk-efficient package manager (required — npm/yarn won't work) | npm install -g pnpm |
| Git | 2.30+ | Version control | https://git-scm.com |
| Docker Desktop | 4+ | Runs WordPress + MariaDB locally via Docker Compose | https://docker.com/products/docker-desktop |
| Turborepo | auto | Monorepo build orchestration (installed via pnpm, no global install needed) | Included in devDependencies |
Docker is only required if you need to work on the WordPress integration. The frontend apps (web, docs, cms) run without Docker. If you only need the docs site or the main frontend, skip Docker and use pnpm dev directly.
Verify your setup:
node -v # v20.x or higher pnpm -v # 9.x or higher git -v # git version 2.30+ docker -v # Docker version 24+ (optional)
Setup
Clone the repository
git clone https://github.com/itu-codeworkshop/itu-monorepo.git cd itu-monorepo
Install dependencies
pnpm reads the workspace configuration and links all internal packages automatically.
pnpm install
The preinstall script enforces pnpm — if you accidentally run npm install or yarn, it will fail with a helpful message.
Start the dev servers
pnpm dev
This starts all apps concurrently via Turborepo. Each app binds to its own port:
| App | Port | URL |
|---|---|---|
apps/web | 3000 | http://localhost:3000 |
apps/cms | 3001 | http://localhost:3001 |
apps/docs | 3002 | http://localhost:3002 |
apps/gateway | 4000 | http://localhost:4000 |
Start WordPress (optional)
If you need the WordPress environment for content editing or plugin development:
pnpm dev:wp
This runs docker compose up with WordPress (port 8080), MariaDB, and phpMyAdmin (port 8081). The ITU theme is mounted from apps/wp-theme/.
To run everything together (all apps + WordPress):
pnpm dev:all
| Service | Port | URL |
|---|---|---|
| WordPress | 8080 | http://localhost:8080 |
| phpMyAdmin | 8081 | http://localhost:8081 |
| MariaDB | 3306 | Internal only |
Available Scripts
These are the main scripts available at the monorepo root. All turbo commands run across every workspace in the correct dependency order.
| Script | Command | Description |
|---|---|---|
pnpm dev | turbo dev | Start all app dev servers concurrently with hot reload |
pnpm dev:wp | docker compose up | Start the WordPress + MariaDB + phpMyAdmin Docker stack |
pnpm dev:all | concurrently dev + dev:wp | Start everything — all apps and the WordPress stack together |
pnpm build | turbo build | Production build of all apps and packages (tsup + Next.js) |
pnpm lint | turbo lint | Run ESLint across all workspaces |
pnpm type-check | turbo type-check | Run TypeScript type checking (tsc --noEmit) across all workspaces |
pnpm test | turbo test | Run tests across all workspaces |
pnpm ai:sync | node scripts/ai-sync.mjs | Sync AI skills from .ai/ sources to provider outputs (.claude/, .cursor/, .codex/) |
pnpm ui:add | shadcn@latest add | Add a shadcn/ui component to @itu/ui |
pnpm docs-ui:add | shadcn@latest add | Add a shadcn/ui component to @itu/docs-ui |
Package-level scripts
Each app and package also has its own scripts. Some notable ones:
| Package | Script | Description |
|---|---|---|
@itu/ui | pnpm build | Bundles with tsup, then extracts props JSON and variant JSON |
@itu/ui | pnpm a11y --all | Run axe-core accessibility audit on all components |
@itu/ui | pnpm a11y button | Run a11y audit on a specific component |
@itu/docs | pnpm prebuild | Bridge concepts docs + generate sidebar navigation |
@itu/docs | pnpm postbuild | Index all pages with Pagefind for static search |
What's next?
Explore the Repository Structure to understand how the code is organised, or jump straight to the Design System to see the visual foundations.