Build & Deployment Process

Documentation Status: This documentation describes the planned API design for the .do platform. Code examples represent the intended interface and may not reflect the current implementation state. See roadmap for implementation status.

Understanding how your MDX code is transformed and deployed to various targets.

Overview

The .do platform uses a sophisticated build pipeline that:

Parses MDX files into AST (Abstract Syntax Tree)
Analyzes components, functions, and dependencies
Optimizes code for target deployment
Bundles for production
Deploys to infrastructure

graph LR A[MDX Source] --> B[Parse] B --> C[Transform] C --> D[Optimize] D --> E[Bundle] E --> F[Deploy] B --> B1[AST Generation] C --> C1[Code Transform] C --> C2[Dependency Analysis] D --> D1[Tree Shaking] D --> D2[Minification] E --> E1[Code Splitting] E --> E2[Asset Optimization] F --> F1[Infrastructure]

Local Development

Setup

# Install dependencies
pnpm install

# Start development server
pnpm dev

# The dev server provides:
# - Hot module replacement
# - TypeScript type checking
# - MDX compilation
# - Error overlay

Development Workflow

---
title: My Feature
---

// 1. Write your MDX code
export async function getData() {
return await $.db.items.find()
}

export function MyComponent() {
  const data = $.data.use(getData)
  return <div>{JSON.stringify(data)}</div>

}

Changes are instantly reflected in your browser with HMR (Hot Module Replacement).

Type Checking

# Check types
pnpm typecheck

# Watch mode
pnpm typecheck --watch

The platform provides full TypeScript support:

// Automatic type inference
const data = await getData()
//    ^? { id: string; name: string }[]

// Type-safe functions
export async function createItem(data: ItemData): Promise<Item> {
  return await $.db.items.create(data)
}

Build Process

Development Build

pnpm build:dev

Development builds include:

Source maps for debugging
Unminified code for readability
Development warnings
Hot reload capabilities

Production Build

pnpm build

Production builds include:

Minification
Tree-shaking (removes unused code)
Code splitting
Asset optimization
Source map generation (optional)

Build Output

dist/
├── agents/          # Compiled agents
│   └── my-agent.js
├── apis/            # API endpoints
│   └── my-api.js
├── apps/            # Application bundles
│   └── my-app/
│       ├── index.html
│       ├── main.js
│       └── assets/
├── sites/           # Static sites
│   └── my-site/
├── services/        # Service packages
│   └── my-service.js
└── workflows/       # Workflow definitions
    └── my-workflow.js

MDX Compilation

flowchart TB A[MDX File] --> B{Parse Phase} B --> C[Frontmatter] B --> D[Markdown] B --> E[JSX] B --> F[JavaScript] C --> G[Transform Phase] D --> G E --> G F --> G G --> H[Runtime Context] G --> I[Dead Code Elimination] G --> J[Constant Folding] H --> K[Optimization Phase] I --> K J --> K K --> L[Production Bundle]

Parse Phase

MDX files are parsed into:

Frontmatter - YAML metadata
Markdown - Content sections
JSX - React components
JavaScript - Functions and logic

---
title: Example # ← Frontmatter
description: Demo
---

# Hello # ← Markdown

<Button /> # ← JSX

export function fn() {} # ← JavaScrip

t

Transform Phase

The platform transforms your code:

// Your MDX code
export async function getData() {
  return await $.db.items.find()
}

// Transforms to (simplified):
export async function getData() {
  const runtime = await getRuntimeContext()
  return await runtime.db.items.find()
}

Optimization Phase

Optimizations applied:

Dead code elimination - Removes unused code
Constant folding - Evaluates constants at build time
Function inlining - Inlines small functions
Asset optimization - Compresses images, CSS, etc.

Deployment Targets

graph TB A[Built Artifacts] --> B{Deployment Type} B --> C[API Deployment] B --> D[App Deployment] B --> E[Agent Deployment] B --> F[Service Deployment] C --> C1[Cloudflare Workers] C --> C2[AWS Lambda] C --> C3[Google Cloud Functions] D --> D1[Static Site - SSG] D --> D2[Server-Side Rendered - SSR] D --> D3[Incremental Static Regeneration - ISR] D --> D4[Single Page App - SPA] E --> E1[Long-running Processes] E --> E2[Serverless Functions] E --> E3[Durable Workflows] F --> F1[.do Marketplace] F --> F2[Private Registry] F --> F3[Self-hosted]

API Deployment

pnpm deploy:api

APIs are deployed as:

Cloudflare Workers (default)
AWS Lambda
Google Cloud Functions
Self-hosted

Deployment includes:

API Gateway configuration
Rate limiting rules
Authentication setup
Monitoring instrumentation

App Deployment

pnpm deploy:app

Apps can be deployed as:

Static Site (SSG) - Pre-rendered HTML
Server-Side Rendered (SSR) - Dynamic rendering
Incremental Static Regeneration (ISR) - Hybrid approach
Single Page App (SPA) - Client-side only

Agent Deployment

pnpm deploy:agent

Agents are deployed as:

Long-running processes - Kubernetes pods
Serverless functions - Event-driven execution
Durable workflows - With state persistence

Service Deployment

pnpm deploy:service

Services are packaged and deployed to:

.do marketplace - Public distribution
Private registry - Internal use
Custom infrastructure - Self-hosted

Environment Configuration

Environment Variables

# .env
DATABASE_URL=postgres://...
API_KEY=sk_...
NODE_ENV=production

// Access in code
export async function getData() {
  const db = await connectDatabase(process.env.DATABASE_URL)
  return await db.query('SELECT * FROM items')
}

Environment-Specific Builds

// do.config.ts
export default {
  environments: {
    development: {
      api: 'http://localhost:3000',
      database: 'postgres://localhost/dev',
    },
    staging: {
      api: 'https://staging-api.example.do',
      database: process.env.STAGING_DATABASE_URL,
    },
    production: {
      api: 'https://api.example.do',
      database: process.env.DATABASE_URL,
    },
  },
}

Continuous Deployment

flowchart LR A[Git Push] --> B[CI Trigger] B --> C[Install Dependencies] C --> D[Run Tests] D --> E{Tests Pass?} E -->|No| F[Notify Failure] E -->|Yes| G[Build] G --> H[Deploy to Staging] H --> I[Smoke Tests] I --> J{Tests Pass?} J -->|No| K[Rollback] J -->|Yes| L[Deploy to Production] L --> M[Health Check] M --> N{Healthy?} N -->|No| O[Auto Rollback] N -->|Yes| P[Success]

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - run: pnpm install
      - run: pnpm build
      - run: pnpm deploy
        env:
          DO_TOKEN: ${{ secrets.DO_TOKEN }}

Automatic Deployments

// do.config.ts
export default {
  deploy: {
    // Deploy on git push
    onPush: {
      branch: 'main',
      environment: 'production',
    },

    // Preview deployments for PRs
    onPullRequest: {
      environment: 'preview',
      domain: (pr) => `pr-${pr.number}.preview.example.do`,
    },
  },
}

Build Optimization

Code Splitting

Automatically split code by route:

// Automatically creates separate bundles
export default {
  apps: [
    {
      routes: {
        '/': HomePage, // → home.bundle.js
        '/dashboard': Dashboard, // → dashboard.bundle.js
        '/settings': Settings, // → settings.bundle.js
      },
    },
  ],
}

Asset Optimization

export default {
  build: {
    optimization: {
      images: {
        formats: ['webp', 'avif'],
        quality: 80,
        sizes: [640, 750, 828, 1080, 1200],
      },
      css: {
        minify: true,
        modules: true,
      },
      javascript: {
        minify: true,
        target: 'es2020',
        format: 'esm',
      },
    },
  },
}

Caching Strategy

export default {
  build: {
    cache: {
      // Cache dependencies
      node_modules: true,

      // Cache build artifacts
      buildCache: true,

      // CDN caching
      cdn: {
        static: '1y', // Static assets
        html: '1h', // HTML pages
        api: '5m', // API responses
      },
    },
  },
}

Testing

Unit Tests

import { test } from 'vitest'
import { getData } from './my-feature.mdx'

test('getData returns items', async () => {
  const items = await getData()
  expect(items).toBeInstanceOf(Array)
})

Integration Tests

test('full workflow', async () => {
  // Create item
  const item = await createItem({ name: 'Test' })

  // Verify in database
  const found = await getItem(item.id)
  expect(found).toEqual(item)

  // Delete item
  await deleteItem(item.id)

  // Verify deletion
  const deleted = await getItem(item.id)
  expect(deleted).toBeNull()
})

E2E Tests

import { test } from '@playwright/test'

test('user can create item', async ({ page }) => {
  await page.goto('/')
  await page.fill('input[name="name"]', 'New Item')
  await page.click('button[type="submit"]')

  await expect(page.locator('.item')).toHaveText('New Item')
})

Deployment CLI

Deploy Command

# Deploy everything
pnpm do deploy

# Deploy specific target
pnpm do deploy:api
pnpm do deploy:app
pnpm do deploy:agent

# Deploy to specific environment
pnpm do deploy --env staging
pnpm do deploy --env production

Rollback

# List deployments
pnpm do deployments list

# Rollback to previous
pnpm do rollback

# Rollback to specific version
pnpm do rollback --version v1.2.3

Deployment Status

# Check deployment status
pnpm do status

# View logs
pnpm do logs

# Monitor metrics
pnpm do metrics

Troubleshooting

Build Errors

# Clear cache and rebuild
pnpm clean
pnpm build

# Verbose output
pnpm build --verbose

# Debug mode
pnpm build --debug

Common Issues

Issue: Module not found

# Ensure dependencies are installed
pnpm install

# Clear cache
rm -rf node_modules/.cache

Issue: Type errors

# Regenerate types
pnpm typecheck --force

Issue: Build timeout

// Increase timeout in config
export default {
  build: {
    timeout: 600000, // 10 minutes
  },
}

Performance Monitoring

Build Metrics

# Analyze build
pnpm build --analyze

# Output:
# Bundle sizes:
# - main.js: 245 KB
# - vendor.js: 589 KB
# - styles.css: 12 KB
#
# Build time: 12.4s

Runtime Metrics

// Automatic performance tracking
export default {
  monitoring: {
    performance: {
      enabled: true,
      sampleRate: 1.0,
      metrics: ['fcp', 'lcp', 'fid', 'cls', 'ttfb'],
    },
  },
}

Configuration - Deployment configuration
Examples - Deployment examples
Code Deployment - Overview
- Best Practices - Development best practices

Build & Deployment Process

On this page