Skip to main content

​
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 install alchemy

​
TypeScript Configuration

Alchemy is built with TypeScript and works best with a properly configured tsconfig.json. 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 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
  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 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 install @octokit/rest
Environment Variables:
.env
GITHUB_TOKEN=ghp_your_personal_access_token
ALCHEMY_PASSWORD=your-encryption-password

​
Database Providers

npm install @neondatabase/serverless
.env
NEON_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 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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us