Installation

Install Alchemy and set up your development environment

Requirements

Alchemy requires one of the following JavaScript runtimes:

• Node.js 18.0.0 or higher
• Bun 1.0.0 or higher (recommended for best performance)

We recommend Bun for the best developer experience. It’s significantly faster than Node.js and has built-in TypeScript support.

Package Installation

Install Alchemy using your preferred package manager:

npm

npm install alchemy

TypeScript Configuration

Alchemy is built with TypeScript and works best with a properly configured tsconfig.json.

Recommended TypeScript Config

Create or update your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowJs": true,
    "checkJs": false,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "allowSyntheticDefaultImports": true,
    "types": ["@cloudflare/workers-types"]
  },
  "include": ["src/**/*", "alchemy.run.ts"],
  "exclude": ["node_modules", ".alchemy"]
}

The "types": ["@cloudflare/workers-types"] is only needed if you’re using Cloudflare Workers. Remove it if you’re using other providers.

Provider-Specific Setup

Depending on which cloud providers you plan to use, you may need additional dependencies.

Cloudflare

For Cloudflare Workers, R2, D1, KV, and other services:

npm

npm install @cloudflare/workers-types wrangler

Environment Variables:

.env

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token
ALCHEMY_PASSWORD=your-encryption-password

How to get Cloudflare credentials

1. Account ID: Log into Cloudflare dashboard, find it on the right sidebar
2. API Token: Create at API Tokens page
   • Use “Edit Cloudflare Workers” template
   • Grant Account > Workers Scripts > Edit
   • Grant Account > Account Settings > Read
3. Password: Choose a strong password for encrypting secrets

AWS

For AWS Lambda, DynamoDB, S3, and other services:

npm

npm install @aws-sdk/client-lambda @aws-sdk/client-dynamodb @aws-sdk/client-s3 @aws-sdk/client-iam

Environment Variables:

.env

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
ALCHEMY_PASSWORD=your-encryption-password

GitHub

For managing GitHub repositories, secrets, and actions:

npm

npm install @octokit/rest

Environment Variables:

.env

GITHUB_TOKEN=ghp_your_personal_access_token
ALCHEMY_PASSWORD=your-encryption-password

Database Providers

Neon

npm install @neondatabase/serverless

.env

NEON_API_KEY=your-api-key

PlanetScale

npm install @planetscale/database

.env

PLANETSCALE_TOKEN=your-token
PLANETSCALE_ORG=your-org

Prisma Postgres

npm install @prisma/client

.env

PRISMA_API_KEY=your-api-key

Project Structure

Here’s a recommended project structure for an Alchemy project:

my-project/
├── .alchemy/              # State directory (gitignored)
│   └── my-app/
│       └── stage-name/
│           └── *.json     # Encrypted state files
├── src/
│   ├── index.ts          # Your application code
│   └── worker.ts
├── migrations/           # Database migrations (if using D1)
│   └── 0001_initial.sql
├── .env                  # Environment variables (gitignored)
├── .gitignore
├── alchemy.run.ts        # Infrastructure definition
├── package.json
└── tsconfig.json

.gitignore Configuration

Make sure to ignore sensitive files:

.gitignore

# Dependencies
node_modules/

# Alchemy state (contains encrypted secrets)
.alchemy/

# Environment variables
.env
.env.local
.env.*.local

# Build outputs
dist/
build/
.output/

# IDE
.vscode/
.idea/

Never commit .alchemy/ or .env files to version control. They contain encrypted secrets and sensitive state.

Verify Installation

Create a simple test file to verify everything is working:

test-alchemy.ts

import alchemy from "alchemy";

const app = await alchemy("test-app");

console.log("✅ Alchemy is installed correctly!");
console.log(`App: ${app.name}`);
console.log(`Stage: ${app.stage}`);

await app.finalize();

Run it:

bun

bun test-alchemy.ts

You should see:

✅ Alchemy is installed correctly!
App: test-app
Stage: your-username

CLI Commands

Alchemy scripts support several CLI flags for different operations:

Deployment Commands

Deploy (default)

bun ./alchemy.run.ts

Common Flag Combinations

# Local development with auto-reload
bun --watch ./alchemy.run.ts --local

# Deploy to production stage
bun ./alchemy.run.ts --stage prod

# Destroy production resources
bun ./alchemy.run.ts --stage prod --destroy

# Adopt existing infrastructure
bun ./alchemy.run.ts --adopt --force

IDE Setup

VS Code

Install recommended extensions:

1. TypeScript and JavaScript Language Features (built-in)
2. ESLint - For linting
3. Prettier - For code formatting

Add to .vscode/settings.json:

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

IntelliJ / WebStorm

1. Enable TypeScript support: Settings → Languages & Frameworks → TypeScript
2. Set TypeScript version to project version
3. Enable ESLint and Prettier in settings

Troubleshooting

Module Resolution Errors

If you see “Cannot find module ‘alchemy’”:

1. Make sure alchemy is in your package.json dependencies
2. Run npm install or bun install
3. Check that "moduleResolution": "bundler" is in your tsconfig.json

Type Errors with Workers Types

If you see type errors with Cloudflare Workers:

1. Install types: npm install -D @cloudflare/workers-types
2. Add to tsconfig.json:
   {
     "compilerOptions": {
       "types": ["@cloudflare/workers-types"]
     }
   }
   

Permission Errors

If deployment fails with permission errors:

1. Verify your API credentials in .env
2. Check that your API token has the required permissions
3. For Cloudflare: Ensure you have Workers Scripts > Edit permission

State File Corruption

If state files are corrupted:

1. Back up .alchemy/ directory
2. Delete corrupted state files
3. Run with --adopt to re-adopt existing resources

bun ./alchemy.run.ts --adopt --force

Next Steps

Quickstart

Deploy your first Cloudflare Worker in 5 minutes

Core Concepts

Learn about Resources, Scopes, and State

Providers

Explore all available cloud providers

Examples

Browse complete example projects

Need help? Join our Discord community or open an issue on GitHub.