Copy page

Developer

Local Setup

Guide to running the Twin platform locally for development.

Prerequisites

Tool	Version	Notes
Node.js	20+	LTS recommended
PostgreSQL	15	Local instance
Git	Latest

Database Setup

Create the development database:

Code
createdb twin-dashboard

Default connection string:

Code
postgres://postgres:postgres@localhost:5432/twin-dashboard

Backend

Code
cd twin-backend

# Install dependencies
npm install

# Run migrations
cd packages/database
npm run migrate
cd ../..

# Run seeds (optional -- populates test data)
cd packages/database
npm run seed
cd ../..

# Build packages in dependency order
npm run build       -w packages/utils
npm run build:types -w packages/utils
npm run build       -w packages/database
npm run build:types -w packages/database
npm run build       -w packages/shared
npm run build:types -w packages/shared
npm run build       -w packages/dashboard

# Start the dashboard API
npm run dev -w packages/dashboard

# Start the platform API (separate terminal)
npm run dev -w packages/platform

# Start the cron service (separate terminal)
npm run dev -w apps/cron-service

{% hint style="warning" %} Always run both build and build:types for each package. Skipping build:types leaves stale type declarations -- you will see Property X does not exist on type Y errors in consumers. {% endhint %}

Dashboard Frontend

Code
cd twin-dashboard-frontend

# Install dependencies
npm install

# Create .env in project root
cat > .env << EOF
VITE_API_URL=http://localhost:3000
VITE_WALLET_CONNECT_PROJECT_ID=development
EOF

# Start dev server
npm run dev

{% hint style="info" %} VITE_WALLET_CONNECT_PROJECT_ID can be set to development locally. WalletConnect features will show a console warning but function for testing. For production-like behavior, get a project ID from cloud.reown.com. {% endhint %}

Platform Frontend

Code
cd twin-platform-frontend

# Install dependencies
npm install

# Create .env in project root
cat > .env << EOF
VITE_API_URL=http://localhost:3001
VITE_WALLET_CONNECT_PROJECT_ID=development
EOF

# Start dev server
npm run dev

Test User

After running seeds, a test user is available:

Field	Value
Email	test@example.com
Password	SecurePassword123!
Account	Acme Corp
Role	Admin

Troubleshooting

Problem	Cause	Solution
Property X does not exist on type Y	Stale .d.ts in dist	Run npm run build:types for the affected package
Cannot find module '@twin/database'	Packages not built	Run the full build pipeline in order
ECONNREFUSED :5432	PostgreSQL not running	Start PostgreSQL service
relation "X" does not exist	Migrations not run	Run npm run migrate in packages/database
ProjectNotFound code 3000	Invalid WalletConnect project ID	Set VITE_WALLET_CONNECT_PROJECT_ID in .env
403 Forbidden on new endpoint	Route not in permissions	Add to routes-permissions.ts in shared
import { Knex } error in migration	CJS/ESM mismatch	Use import type { Knex } instead
Cron job not running	Not registered in all 3 places	Check cron-keys.ts, manager.ts, cron-handlers.ts