Development Guide

Set up your development environment for Go Bananas!.

Prerequisites

Required Software

• Node.js 24 - JavaScript runtime
• npm or pnpm - Package manager
• Git - Version control
• VS Code (recommended) - IDE

Optional but Recommended

• Wrangler CLI - Cloudflare development
• SQLite viewer - Database inspection
• REST client - API testing (Thunder Client, Postman)

Initial Setup

1. Clone Repository

git clone https://github.com/davendra/go-bananas-app.git
cd go-bananas-app

2. Install Dependencies

npm install

# Also install frontend dependencies
npm --prefix frontend install

3. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env with your values
# Required: ENCRYPTION_KEY (generate with: openssl rand -hex 32)

4. Set Up Local Database

# Create local D1 database
wrangler d1 create go-bananas-db --local

# Initialize schema
npm run db:init

5. Start Development Server

# Backend
npm run dev

# Frontend (in separate terminal)
npm run frontend:dev

Development Workflow

Backend Development

Edit code, auto-reload, test, and commit

The development server auto-reloads on file changes:

npm run dev
# Server at http://localhost:8787

Frontend Development

npm run frontend:dev
# Server at http://localhost:5173

Frontend proxies API requests to the backend.

Full Stack

Run both in separate terminals or use:

# Terminal 1
npm run dev

# Terminal 2
npm run frontend:dev

Project Structure

Backend (src/)

src/
├── index.ts              # Worker entry point
├── mcp/
│   └── agent.ts          # MCP Durable Object
├── tools/                # MCP tools
│   ├── generate-image.ts
│   ├── edit-image.ts
│   ├── create-character.ts
│   └── ...
├── api/                  # REST API
│   ├── tenant-api.ts     # Tenant endpoints
│   ├── admin.ts          # Admin endpoints
│   └── http.ts           # HTTP helpers
├── auth/                 # Authentication
│   └── tenant-resolver.ts
├── services/             # Business logic
│   ├── gemini-client.ts
│   ├── image-storage.ts
│   └── usage.ts
└── types/                # Type definitions
    └── index.ts

Frontend (frontend/)

frontend/
├── src/
│   ├── App.tsx           # Root component
│   ├── views/            # Page components
│   │   ├── DashboardView.tsx
│   │   ├── GalleryView.tsx
│   │   └── ...
│   ├── components/       # Reusable components
│   ├── hooks/            # Custom hooks
│   ├── context/          # React context
│   └── api/              # API client
├── public/               # Static assets
└── index.html            # HTML template

Key Files

Worker Entry (src/index.ts)

Handles routing and authentication:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // Route based on path
    // Authenticate requests
    // Forward to appropriate handler
  }
};

MCP Agent (src/mcp/agent.ts)

Durable Object for MCP protocol:

export class GoBananasMcpAgent extends DurableObject {
  // Register all MCP tools
  // Handle tool invocations
  // Manage session state
}

Tool Implementation (src/tools/*.ts)

Each tool follows the pattern:

// Schema
export const ToolInputSchema = z.object({...});

// Handler
export async function toolHandler(env, tenantId, sessionId, geminiApiKey, params) {
  // Implementation
}

// Definition
export function getToolDefinition() {
  return { name, description, inputSchema };
}

Local Database

Access Local D1

# Execute query
wrangler d1 execute go-bananas-db --local --command "SELECT * FROM tenants"

# Run SQL file
wrangler d1 execute go-bananas-db --local --file query.sql

Reset Database

# Delete and recreate
rm -rf .wrangler/state
npm run db:init

Create Test Tenant

# Use the setup script
ENCRYPTION_KEY=$(openssl rand -hex 32) npm run setup-tenant

Testing

Run All Tests

npm run test:all

Run Specific Tests

# Single test file
npm test -- tests/generate-image.test.ts

# Tests matching pattern
npm test -- --grep "image generation"

Watch Mode

npm test -- --watch

Coverage

npm test -- --coverage

Debugging

Console Logging

Add temporary logs:

console.log('Debug:', JSON.stringify(data, null, 2));

View in terminal running npm run dev.

VS Code Debugging

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
      "args": ["run", "${relativeFile}"],
      "console": "integratedTerminal"
    }
  ]
}

Wrangler Debugging

# Verbose logging
wrangler dev --log-level debug

# Inspect Durable Objects
wrangler dev --inspect

Common Development Tasks

Add New API Endpoint

1. Add route in src/api/tenant-api.ts:

if (method === 'GET' && pathMatch(path, '/api/new-endpoint')) {
  return handleNewEndpoint(request, env, tenantId);
}

2. Implement handler:

async function handleNewEndpoint(
  request: Request,
  env: Env,
  tenantId: string
): Promise<Response> {
  // Implementation
  return jsonResponse({ success: true, data: result });
}

Add Database Migration

1. Create migration file:

touch migrations/0013_add_new_feature.sql

2. Write migration:

-- migrations/0013_add_new_feature.sql
ALTER TABLE images ADD COLUMN new_field TEXT;
CREATE INDEX idx_images_new_field ON images(new_field);

3. Apply migration:

npm run db:migrate

Add Frontend Component

1. Create component:

// frontend/src/components/NewComponent.tsx
export function NewComponent({ prop }: { prop: string }) {
  return <div>{prop}</div>;
}

2. Use in view:

import { NewComponent } from '../components/NewComponent';

Environment Variables

Development (.env)

# Required
ENCRYPTION_KEY=your-64-char-hex-key

# Optional
LOG_LEVEL=debug

Local Wrangler

Configure in wrangler.jsonc:

{
  "vars": {
    "ENVIRONMENT": "development",
    "LOG_LEVEL": "debug"
  }
}

Code Quality

Type Checking

npm run typecheck

Linting

npm run lint

# Fix auto-fixable issues
npm run lint -- --fix

Formatting

npx prettier --write .

Hot Reload

Wrangler automatically reloads on file changes. If reload doesn't work:

1. Check terminal for errors
2. Try stopping and restarting npm run dev
3. Clear Wrangler cache: rm -rf .wrangler/state

Next Steps

• Code Style →
• Testing →
• Contributing Index →