Development Setup
This guide covers everything needed to get The Shift Platform running locally for development.
Prerequisites
| Tool | Version | Check Command |
|---|---|---|
| Bun | >= 1.0 | bun --version |
| Node.js | >= 18 (for npx) | node --version |
| Git | any recent | git --version |
| Docker | any recent | docker --version |
| kind | any recent | kind --version |
| kubectl | any recent | kubectl version --client |
Bun is the primary runtime. Node.js is needed only for npx (used by Convex CLI).
Clone the Repository
Clone with submodules to pull all service repos:
git clone --recurse-submodules https://github.com/the-shift-dev/platform.git
cd platform
If you already cloned without --recurse-submodules:
git submodule update --init --recursive
Install Dependencies
bun install
This installs dependencies for the root workspace and all submodule packages.
Running the Dev Server
Start all services and the gateway:
bun run dev
This launches:
- The gateway on port 3000
- Each service's API on its dedicated port (4001-4010)
- Each service's web UI on its dedicated port (4101-4110)
Verify the gateway is running:
curl http://localhost:3000/healthz
# {"status":"ok","service":"shift-gateway"}
Running Tests
Run all tests across all services:
bun run test
Run tests for a specific service:
cd yellowpages
bun test
Run a specific test file:
bun test yellowpages/packages/api/src/routes.test.ts
Type Checking
The platform uses TypeScript strict mode. Check types across the workspace:
bun run typecheck
Linting and Formatting
The platform uses Biome for both linting and formatting:
# Check for lint and format issues
bun run check
# Auto-fix format issues
bun run format
Building
Build all web assets and the gateway:
bun run build
Build the Docker image:
bun run build:docker
# or
docker build -t shift-platform:dev .
Clean
Remove build artifacts and dependencies:
bun run clean
This removes node_modules/, dist/, and *.tsbuildinfo files across the workspace.
Environment Variables
For local development with file-based storage, no environment variables are needed. For Convex storage or authentication, see the Environment Variables reference.
Common local overrides:
# Use file-based storage instead of Convex
SHIFT_STORAGE=file bun run dev
# Enable debug logging
LOG_LEVEL=debug bun run dev
Troubleshooting
Stale platform-core symlinks
If you see errors about missing exports from @shift/platform-core, the cached symlink may be stale:
bun install # Re-running install usually fixes it
Submodule not initialized
If a service directory is empty:
git submodule update --init --recursive
Port already in use
If a dev port is already in use, kill the existing process or change the port. The dev script starts multiple processes; use Ctrl+C to stop them all.