Monorepo Setup

Set up Alchemy in a monorepo with multiple applications and shared infrastructure

Monorepo Setup

Alchemy works seamlessly in monorepo setups, allowing you to manage multiple applications and shared infrastructure in a single repository. This guide shows you how to structure and deploy a monorepo with Alchemy.

Monorepo Structure

A typical Alchemy monorepo looks like this:

my-monorepo/
  apps/
    frontend/
      alchemy.run.ts
      src/
      package.json
    backend/
      alchemy.run.ts
      src/
      package.json
    analytics/
      alchemy.run.ts
      src/
      package.json
  package.json          # Root package.json
  turbo.json            # Turborepo config (optional)
  tsconfig.json         # Shared TypeScript config
  .env.example

Setting Up a Monorepo

Resource Sharing Between Apps

Apps can import and use resources from other apps:

Export Resources

apps/backend/alchemy.run.ts

import alchemy from "alchemy";
import { Worker, D1Database } from "alchemy/cloudflare";

const app = await alchemy("backend");

const db = await D1Database("db", {
  name: "shared-database"
});

// Export both the worker and database
export const backend = await Worker("api", {
  entrypoint: "./src/index.ts",
  bindings: { DB: db }
});

export const database = db;

await app.finalize();

Import and Use Resources

apps/frontend/alchemy.run.ts

import alchemy from "alchemy";
import { Vite } from "alchemy/cloudflare";
import { backend, database } from "backend/alchemy";

const app = await alchemy("frontend");

const frontend = await Vite("website", {
  bindings: {
    API: backend,        // Reference to backend worker
    DB: database         // Direct access to backend's database
  }
});

await app.finalize();

Alchemy automatically handles resource dependencies and creates them in the correct order.

Deployment

Deploy All Apps

Deploy all applications in dependency order:

# Using Turborepo
bun run deploy

# Or manually
cd apps/backend && bun ./alchemy.run.ts
cd apps/analytics && bun ./alchemy.run.ts
cd apps/frontend && bun ./alchemy.run.ts

Turborepo ensures:

• Dependencies are deployed first
• Apps are deployed in parallel when possible
• Failures are handled gracefully

Deploy Specific App

cd apps/backend
bun ./alchemy.run.ts

Deploy with Stage

bun run deploy -- --stage production

Destroying Resources

Destroy All Apps

bun run destroy

This destroys resources in reverse dependency order:

1. Frontend (destroys last)
2. Backend and Analytics (can destroy in parallel)

Destroy Specific App

cd apps/backend
bun ./alchemy.run.ts --destroy

Be careful when destroying apps with shared resources. Other apps may depend on them.

Environment Variables

Shared Environment Variables

Use a root .env file for shared configuration:

.env

# Shared credentials
ALCHEMY_PASSWORD=shared-password
CLOUDFLARE_API_KEY=your-api-key
CLOUDFLARE_ACCOUNT_ID=your-account-id

# Shared secrets
API_KEY=shared-api-key
DATABASE_URL=postgres://...

App-Specific Environment Variables

Each app can have its own .env.local:

apps/backend/.env.local

# Backend-specific configuration
BACKEND_PORT=3000
BACKEND_LOG_LEVEL=debug

Loading Environment Variables

apps/backend/alchemy.run.ts

import "dotenv/config";  // Loads from root .env
import alchemy from "alchemy";

// Access shared environment variables
const app = await alchemy("backend", {
  password: process.env.ALCHEMY_PASSWORD
});

Stages and Environments

Per-Stage Deployments

Deploy different stages of the monorepo:

# Development
bun run deploy -- --stage dev

# Staging
bun run deploy -- --stage staging

# Production
bun run deploy -- --stage production

Environment-Specific Configuration

apps/backend/alchemy.run.ts

import alchemy from "alchemy";

const app = await alchemy("backend");
const stage = app.stage;  // "dev", "staging", or "production"

const worker = await Worker("api", {
  entrypoint: "./src/index.ts",
  bindings: {
    // Environment-specific configuration
    LOG_LEVEL: stage === "production" ? "error" : "debug",
    API_URL: stage === "production" 
      ? "https://api.example.com"
      : "https://staging-api.example.com"
  }
});

await app.finalize();

State Management

Each application maintains its own state:

.alchemy/
  backend/
    dev/
      state.json
    production/
      state.json
  frontend/
    dev/
      state.json
    production/
      state.json
  analytics/
    dev/
      state.json
    production/
      state.json

State is isolated per application and stage, allowing independent deployments.

Development Workflow

Local Development

Run all apps locally:

# Using Turborepo
bun run dev

# Or manually
cd apps/backend && bun --watch ./alchemy.run.ts --local &
cd apps/analytics && bun --watch ./alchemy.run.ts --local &
cd apps/frontend && bun --watch ./alchemy.run.ts --local

Watch Mode

Each app can run in watch mode independently:

apps/backend/package.json

{
  "scripts": {
    "dev": "bun --watch ./alchemy.run.ts --local",
    "deploy": "bun ./alchemy.run.ts",
    "destroy": "bun ./alchemy.run.ts --destroy"
  }
}

Best Practices

Example: Complete Monorepo

Here’s a complete example monorepo:

package.json

{
  "name": "monorepo",
  "private": true,
  "scripts": {
    "build": "tsc -b",
    "dev": "turbo run dev",
    "deploy": "tsc -b && turbo run deploy --ui=stream",
    "destroy": "tsc -b && turbo run destroy --ui=stream"
  },
  "workspaces": {
    "packages": ["apps/*"],
    "catalog": {
      "alchemy": "latest",
      "typescript": "^5.8.3"
    }
  },
  "devDependencies": {
    "alchemy": "catalog:",
    "turbo": "^2.5.6",
    "typescript": "catalog:"
  }
}

Troubleshooting

Circular Dependencies

Avoid circular imports between apps:

// ❌ Bad: frontend imports backend, backend imports frontend
// apps/backend/alchemy.run.ts
import { frontend } from "frontend/alchemy";

// apps/frontend/alchemy.run.ts
import { backend } from "backend/alchemy";

Solution: Create a shared package for common resources.

Import Errors

Ensure package exports are configured:

apps/backend/package.json

{
  "exports": {
    "./alchemy": "./alchemy.run.ts"
  }
}

Deployment Order

Use Turborepo’s dependsOn to control order:

turbo.json

{
  "tasks": {
    "frontend#deploy": {
      "dependsOn": ["backend#deploy", "analytics#deploy"]
    }
  }
}

Next Steps

• Deployment - Deploy your monorepo to production
• Testing - Test your monorepo applications
• Creating Resources - Learn more about resource creation