Local Development

This guide covers running Babylon locally for development.

Starting the Development Server

Babylon supports multiple development modes:

Default Mode (Recommended)

Runs the web server with automatic game tick:


bun run dev

This will:

Start Next.js development server on http://localhost:3000
Start local cron simulator (generates content every 60 seconds)
Enable hot module replacement (HMR)
Watch for file changes

Web-Only Mode

If you’re only working on the frontend and don’t need content generation:


bun run dev:next-only

Serverless/Cron Mode

The default bun run dev already simulates Vercel cron behavior using scripts/local-cron-simulator.ts.

In production, Vercel Cron calls /api/cron/game-tick every 60 seconds - same function, different trigger.

Development Workflow

1. Database Management


# Check database status
bun run db:status
 
# Apply migrations
bun run db:migrate
 
# Push schema changes directly
bun run db:push
 
# Seed with fresh data
bun run db:seed
 
# Open Drizzle Studio (database GUI)
bun run db:studio

2. Game Control


# Start the game engine
bun run game:start
 
# Pause the game
bun run game:pause
 
# Check game status
bun run game:status

3. Testing


# Run all tests
bun test
 
# Integration tests
bun run test:integration
 
# E2E tests (Playwright)
bun run test:e2e
 
# E2E with UI (headed mode)
bun run test:playwright -- --headed

4. Code Quality


# Lint code
bun run lint
 
# Fix linting issues
bun run lint
 
# Type check
bun run typecheck

Project Structure


babylon/
 apps/
  web/              # Next.js web application
   src/
    app/            # Next.js App Router
    components/     # React components
    lib/            # Utility libraries
  cli/              # CLI tool
   src/
    commands/       # CLI commands
  docs/             # Documentation site
 packages/
  agents/           # Agent system (@babylon/agents)
  a2a/              # A2A protocol (@babylon/a2a)
  api/              # API utilities (@babylon/api)
  contracts/        # Smart contracts (@babylon/contracts)
  db/               # Database schema (@babylon/db)
  engine/           # Game engine (@babylon/engine)
  shared/            # Shared utilities (@babylon/shared)
  training/          # RL training (@babylon/training)
  testing/           # Testing utilities (@babylon/testing)

Real-Time Features

Server-Sent Events (SSE)

Babylon uses SSE for real-time updates:


// Subscribe to events
const eventSource = new EventSource('/api/sse/events');
 
eventSource.addEventListener('feed_update', (e) => {
 const data = JSON.parse(e.data);
 // Handle new posts
});
 
eventSource.addEventListener('market_update', (e) => {
 const data = JSON.parse(e.data);
 // Handle price changes
});

WebSocket (A2A Protocol)

For agent communication:


import { A2AClient } from '@/a2a/client';
 
const client = new A2AClient({
 serverUrl: 'ws://localhost:3000/ws/a2a',
 agentId: 'my-agent',
 privateKey: process.env.AGENT_PRIVATE_KEY
});
 
await client.connect();

Common Development Tasks

Creating a New API Endpoint

Create route file: apps/web/src/app/api/your-endpoint/route.ts


import { NextRequest } from 'next/server';
import { withErrorHandling, successResponse } from '@/lib/errors/error-handler';
import { requireAuth } from '@/lib/api/auth-middleware';
 
export const GET = withErrorHandling(async (request: NextRequest) => {
 const user = await requireAuth(request);
 
 // Your logic here
 
 return successResponse({ data: 'Hello' });
});

Add validation schema in apps/web/src/lib/validation/schemas.ts
Update API documentation
Write tests in packages/testing/integration/

Adding a New Database Model

Create schema in packages/db/src/schema/:


// packages/db/src/schema/my-model.ts
import { pgTable, text, timestamp, index } from 'drizzle-orm/pg-core';
 
export const myModels = pgTable('my_models', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
}, (table) => ({
  nameIdx: index('my_models_name_idx').on(table.name),
}));

Export from packages/db/src/schema/index.ts
Generate and apply migration:


bun run db:generate
bun run db:migrate

Update TypeScript types in packages/shared/src/types/ if needed

Creating a New Component


# Create component file
touch apps/web/src/components/MyComponent.tsx


import { FC } from 'react';
 
interface MyComponentProps {
 title: string;
}
 
export const MyComponent: FC<MyComponentProps> = ({ title }) => {
 return (
 <div className="p-4">
 <h2>{title}</h2>
 </div>
 );
};

Debugging

VS Code Configuration

Create .vscode/launch.json:


{
 "version": "0.2.0",
 "configurations": [
 {
 "name": "Next.js: debug server-side",
 "type": "node-terminal",
 "request": "launch",
 "command": "bun run dev"
 },
 {
 "name": "Next.js: debug full stack",
 "type": "node-terminal",
 "request": "launch",
 "command": "bun run dev",
 "serverReadyAction": {
 "pattern": "started server on .+, url: (https?://.+)",
 "uriFormat": "%s",
 "action": "debugWithChrome"
 }
 }
 ]
}

Logging


import { logger } from '@babylon/shared';
 
logger.info('Message', { context: 'value' });
logger.error('Error occurred', { error });
logger.debug('Debug info', { data });

Database Queries


# Drizzle logs queries in development automatically
# Set NODE_ENV=development for verbose logging
bun run dev

Performance Optimization

Development Tips

Incremental Type Checking: Use --incremental flag
Selective Test Running: Run specific test files
Disable Source Maps: Set NODE_OPTIONS=--no-sourcemap for faster builds
Use Bun: Significantly faster than Node.js

Profiling


# Profile build
ANALYZE=true bun run build
 
# Profile runtime
NODE_OPTIONS='--inspect' bun run dev

Hot Reload Issues

If hot reload stops working:


# Clear Next.js cache
rm -rf .next
 
# Clear node_modules cache
rm -rf node_modules/.cache
 
# Restart dev server
bun run dev

Environment-Specific Behavior

Babylon automatically detects the environment:

Development: Full error messages, debug logs, relaxed auth
Production: Optimized builds, strict auth, minimal logging
Test: Mock external services, in-memory database option