Alchemy | Blog

Alchemy's Cloudflare Vite Plugin

Tue, 05 Aug 2025 00:00:00 GMT

Alchemy now ships with plugins for Vite, Astro, SvelteKit, Nuxt, React Router, and TanStack Start that streamline local development by eliminating the need for a .dev.vars file, configuration of wrangler state paths, and other boilerplate.

TLDR: update your vite.config.ts file to use the alchemy plugin instead of the cloudflare plugin for a smoother experience:

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import alchemy from "alchemy/cloudflare/vite";

export default defineConfig({
  plugins: [cloudflare()],
  plugins: [alchemy()],
});

What problem does it solve?

When deploying a Web app in Alchemy, you set secrets using the bindings property:

await Vite("website", {
  bindings: {
    SOME_SECRET: alchemy.secret.env.SOME_SECRET,
  }
})

👍 The alchemy deploy command will build and deploy your website to Cloudflare with the SOME_SECRET as a secure Binding, as expected.

👎 The alchemy dev command, however, would be missing the secret because Cloudflare’s Vite plugin only includes environment variables from .dev.vars.

The old workaround

The workaround was to replicate these values to the .dev.vars file like so:

VITE_SOME_VAR=some-value
SOME_SECRET=some-secret

But, this is redundant and inflexible. As Alchemy users, we want to maintain our configuration and environments in code.

The new solution

We updated the Website resources (and its variants like Vite, Astro, etc.) to generate a temporary wrangler.json file in .alchemy/local/wrangler.json that contains your secrets in plain text:

{
  "name": "website",
  "main": "./src/worker.ts",
  "compatibility_date": "2025-08-02",
  "assets": { "directory": "./dist/client", "binding": "ASSETS" },
  "vars": { "SOME_SECRET": "super secret value!" },
}

vite dev will include the vars when running your Worker locally, so you no longer need a .dev.vars file 🎉.

Our new alchemy vite plugin takes care of configuring the annoying boilerplate:

export default defineConfig({
  plugins: [
    cloudflare({
      path: process.env.ALCHEMY_CLOUDFLARE_PERSIST_PATH ,
      configPath: ".alchemy/local/wrangler.json",
      experimental: { remoteBindings: true }
    })
  ],
  plugins: [alchemy()],
});

Other frameworks

This blog mostly focused on Vite, but we also vend similar plugins for other frameworks that behave differently than Vite.

Astro

astro.config.mjs

import cloudflare from '@astrojs/cloudflare';
import alchemy from 'alchemy/cloudflare/astro';
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
  adapter: alchemy(),
});

SvelteKit

svelte.config.mjs

import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
import adapter from '@sveltejs/adapter-cloudflare';
import alchemy from 'alchemy/cloudflare/sveltekit';

export default {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter()
    adapter: alchemy()
  }
};

Nuxt

nuxt.config.ts

import alchemy from "alchemy/cloudflare/nuxt";

import { defineNuxtConfig } from "nuxt/config";

export default defineNuxtConfig({
  compatibilityDate: '2025-05-15',
  devtools: { enabled: true },
  nitro: {
    preset: "cloudflare-module",
    cloudflare: {
      deployConfig: true,
      nodeCompat: true
    }
    cloudflare: alchemy(),
    prerender: {
      routes: ["/"],
      autoSubfolderIndex: false,
    },
  },
  modules: ["nitro-cloudflare-dev"],
});

React Router

vite.config.ts

import { reactRouter } from "@react-router/dev/vite";
import cloudflare from "@cloudflare/vite-plugin";
import alchemy from "alchemy/cloudflare/react-router";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [
    cloudflare({
      viteEnvironment: {
        name: "ssr",
      },
    }),
    alchemy(),
    reactRouter(),
    tsconfigPaths({
      root: "."
    }),
  ],
});

TanStack Start

vite.config.ts

import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { cloudflareWorkersDevEnvironmentShim } from "alchemy/cloudflare";
import alchemy from "alchemy/cloudflare/tanstack-start";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  server: {
    port: 3000,
  },
  build: {
    target: "esnext",
    rollupOptions: {
      external: ["node:async_hooks", "cloudflare:workers"],
    },
  },
  plugins: [
    cloudflareWorkersDevEnvironmentShim(),
    alchemy(),
    tsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tanstackStart(),
    viteReact(),
  ],
});

What is Alchemy

Tue, 01 Jul 2025 00:00:00 GMT

Alchemy is an embeddable Infrastructure-as-Code (IaC) library written in pure TypeScript that runs anywhere that JavaScript runs - including the browser, serverless functions or even durable workflows.

What is Infrastructure as Code?

Infrastructure-as-Code is the practice of using code to define your infrastructure configuration instead of manually creating it.

Let’s say you need a database. Instead of clicking through a cloud console or executing a CLI command, you simply write:

const database = await Database("main", {
  engine: "postgres",
  size: "small",
});

// Access properties directly
console.log(database.connectionString);

Run this code, and the actual database gets created. Run it twice without changes, and nothing happens. Change the size to "medium" and run it again - your database will be updated. Remove the code and run it again, the database will be deleted.

Your code is the blueprint for repeatable infrastructure. Alchemy keeps track of all the resources and handles the synchronization between your code and the real world.

How is Alchemy different than traditonal IaC?

Unlike similar tools like Terraform, Pulumi, SST and CloudFormation, Alchemy is implemented in pure ESM-native TypeScript code.

The Terraform, Pulumi and SST ecosystem are all tied together. SST is on top of Pulumi, which is again on top of Terraform. Terraform and Pulumi are implemented in Go and generate TypeScript “wrappers” that depend on a separate Go process.

The AWS CDK genereates CloudFormation JSON, depends on a managed service to run and only supports AWS services. Extending CloudFormation requires you deploy a Lambda Function (which is an ordeal).

All together, IaC without Alchemy is a clunky, heavy, opinionated toolchain that mostly works against you as a user. Alchemy simplifies the entire stack down to pure async functions.

Zero Dependencies

Alchemy adopts a philosophy of zero-dependencies and web standards so that it can run anywhere with minimal impact on bundle size.

All you gotta do is install alchemy and you’re good to go.

bun add alchemy

Just Async Functions

Resources in Alchemy are implemented with async functions instead of complex class abstractions with sharp edge gotchas, inter-process-communication or hosted services.

This means you can create resources in any async environment and gain access to its physical properties immediately:

// Create a resource by awaiting a function
const worker = await Worker("api", {
  name: "my-api",
  entrypoint: "./src/index.ts",
});

console.log(worker.workerName); // string

Contrast this with Pulumi which relies on a complex graph abstraction:

const worker = new Worker("api", {
  name: "my-api",
  entrypoint: "./src/index.ts",
});

worker.workerName; // Output<string>

// requires a complex abstraction just to log a value 😵‍💫
pulumi.export(worker.workerName);

Runs Anywhere

Alchemy works in any JavaScript environment including browsers, serverless functions, and durable workflows.

// Browser environment
const app = await alchemy("my-browser-app");

// Lambda function
export const handler = async () => {
  await alchemy.run("customer-id", async () => {
    await Worker(..)
  })
};

Transparent State

State is stored as plain JSON files you can inspect, edit, and version control.

.alchemy/my-app/prod/api.json

{
  "provider": "cloudflare::Worker",
  "status": "created",
  "output": {
    "id": "my-api",
    "url": "https://my-api.workers.dev"
  },
  "props": {
    "name": "my-api",
    "entrypoint": "./src/index.ts"
  }
}

Pluggable State

Alchemy supports custom state backends including file systems, cloud storage, or databases.

// Use Cloudflare R2 for state
import { R2RestStateStore } from "alchemy/cloudflare";

const app = await alchemy("my-app", {
  stateStore: (scope) =>
    new R2RestStateStore(scope, {
      bucketName: "my-state-bucket",
    }),
});

By default, Alchemy assumes you want to store state files locally for development purposes, but since Alchemy can run anywhere - you may want to store state in the the browser, or a Cloudflare Durable Object!

Learn more about state

Direct API Integration

fetch is all you need

Alchemy resources call service APIs directly using fetch, instead of using SDKs that often come with heavy dependencies and runtime requirements.

// Resource implementation using direct API calls
if (this.phase === "delete") {
  await fetch(`https://api.example.com/resources/${this.output.id}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  return this.destroy();
}

Custom Resources in Minutes

Create new resource types with a simple function that implements create, update, and delete operations.

export const Database = Resource(
  "myservice::Database",
  async function (
    this: Context<Database>,
    id: string,
    props: DatabaseProps
  ): Promise<Database> {
    if (this.phase === "delete") {
      // Delete logic
      return this.destroy();
    } else if (this.phase === "update") {
      // Update logic
      return { id: "db-123", ...props };
    } else {
      // Create logic
      return { id: "db-123", ...props };
    }
  }
);

Optimized for AI

Alchemy provides a .cursorrules file to help AI tools generate resource implementations at 90% accuracy on the first try.

// 1. Copy Alchemy's .cursorrules into your repo
// 2. Ask AI: "Create a resource for Neon Database"
// 3. Get a working implementation in seconds

// Result: Complete implementation with proper lifecycle handling
export const Database = Resource(
  "neon::Database",
  async function (
    this: Context<Database>,
    id: string,
    props: DatabaseProps
  ): Promise<Database> {
    // Full resource implementation generated by AI
  }
);

Learn more about building custom resources

Fast Deployments

Alchemy deployments are fast because they run directly in JavaScript without spawning external processes or slow toolchains.

// No IPC, no Go toolchains, no CloudFormation waiting
// Just direct JavaScript execution calling APIs
// $ time bun ./alchemy.run.ts
// real    0m1.234s

Flexible Scoping

Alchemy organizes resources with a hierarchical scope system that supports infinite nesting and isolation.

// Root and stage scopes
const app = await alchemy("my-app", {
  stage: "prod",
  password: "prod-secret", // Encryption password for this scope
});

Secure Secrets

Alchemy encrypts sensitive values in state files.

// Define a secret
const apiKey = alchemy.secret(process.env.API_KEY);

// Use it in a resource
const worker = await Worker("api", {
  bindings: { API_KEY: apiKey },
});

// In state files, it's encrypted
// "API_KEY": { "@secret": "Tgz3e/WAscu4U1oanm5S4YXH..." }

Scoped Encryption and State

Each scope can have a different encryption password and state store.

// Nested scopes can have different passwords and state stores
await alchemy.run(
  "backend",
  {
    password: "backend-secret",
    stateStore: new DatabaseStateStore(),
  },
  async (scope) => {
    // Create resources in this scope
    await Worker("api", {
      /* ... */
    });

    // Deeper nesting works too
    await alchemy.run("database", async () => {
      await Database("main", {
        /* ... */
      });
    });
  }
);

Application Examples

Alchemy works for a wide range of infrastructure use cases.

// Cloudflare Workers and Static Sites
const assets = await Assets({
  path: "./dist",
});

const site = await Worker("Website", {
  name: "my-app",
  bindings: {
    ASSETS: assets,
  },
});

// AWS Lambda Functions
const func = await Function("api", {
  handler: "src/lambda.handler",
  environment: { TABLE_NAME: table.name },
});

// Third-party APIs like Stripe
const product = await Product("pro-plan", {
  name: "Pro Plan",
  description: "Professional subscription tier",
});

Getting Started

Ready to try Alchemy? Check out our Getting Started guide to build your first Alchemy app.

Why IaC needs to be un-bundled

Tue, 08 Apr 2025 00:00:00 GMT

I built Alchemy after years of working with every other option—from CloudFormation and CDK to Pulumi, Terraform, and Kubernetes. IaC is non-negotiable in my opinion and one of my favorite technologies as a developer.

The Tool Journey: From Bad to Worse

I started with CloudFormation since I worked at Amazon, and I really hated it. JSON just isn’t expressive enough for me, and debugging broken stacks was always something I dreaded. I’m pretty sure the CFN website still squashes error messages into a 10-pixel-wide box 😅.

The CDK is an upgrade (yay for TypeScript!), but it’s still limited by the CloudFormation service, which is slow to change and use.

Being developed by corporate giant Amazon, with the founder having moved on to new ideas, you just have to accept that things will move slowly and you have no say or control over that. It’s how things work in big centralized companies.

One major technical wart with the CDK is its awful coupling to synchronous I/O, making it nearly impossible to do anything async. Every user inevitably runs into this, googles it, and is met with “fuck off” in the GitHub issues. Then we’re forced to hack around it, which isn’t pretty. Not allowing async is basically not allowing JavaScript. I doubt it’ll ever be fixed.

They’re also stuck on CommonJS. Taking a dependency on the CDK and using it anywhere other than locally will 10x the size of your app and destroy your developer experience. It’s a tangled mess of complicated, legacy TypeScript code generating complicated, proprietary JSON files uploaded to the complicated, opaque, proprietary CloudFormation service 🫠

Why? How does this serve the user?

Later, I moved to Pulumi, which was a nice change of pace since it runs locally and is much faster. You can cancel a deployment by hitting Ctrl+C (hallelujah!), and it supports more than just AWS, which is great because everything should be managed sensibly in code.

However, Pulumi is largely a wrapper around Terraform. If you thought you were going to escape the layers, you were sorely mistaken. That JavaScript is just lipstick on the pig that is clunky “providers” implemented in Go, running in a separate process. You can’t run Pulumi everywhere (like in the browser), and it even struggles to run in AWS Lambda if you’re using ESM.

Pulumi Custom Resources are possible but feel like an afterthought and are a pain to implement. They have many sharp edges and gotchas, like the resource code having to be serialized and their coupling to CommonJS. If you import the wrong thing with ESM, it just breaks. I couldn’t even use AWS SDK v3 in a simple custom resource because of how leaky these abstractions are.

If Pulumi bricks itself by getting into some weird state, good luck fixing it. Their state files are complicated and their providers are opaque, so you’re stuck running pulumi refresh and praying, or surgically removing and restoring resources one by one. It’s not transparent.

I’ve used Terraform when forced into it. It does exactly what it claims to do, but I don’t love it because it’s a custom DSL with a heavy toolchain. And for what? Calling a few CRUD APIs? Way overkill.

If it doesn’t already exist in Terraform, just forget it. Every time I think about implementing a custom resource for Terraform, I can’t bring myself to do it. Let me just write a function in my language, please!

Lately, I’ve been using SST because I’ve been doing a ton of web development. At first, I really liked SST for its local development experience. sst dev gives you live deploy, a TUI multiplexer, and a proxy from the cloud to your local code. This is great for building web apps in AWS.

But SST is a wrapper around Pulumi! (which is a wrapper around Terraform (which is a wrapper around the underlying SDK ( … ( … ( … )))) …

Layers. Layers. Layers. When will it ever end?

As my app grew, SST’s bugs and opinions ate away at me. I got blocked by broken resources with race conditions that were impossible to work around (still are, by the way). I also wanted to deploy a nested app using another sst.config.ts, but it conflicted with their assumptions around generated sst-env.d.ts files.

Again, I was let down by the complexity and opinions of my chosen IaC framework. And for what? To help me call a few CRUD APIs and track my resources?

Honestly, it seems insane how far we’ve drifted from simplicity in this area. This became even more apparent as I started using Cursor more to write code.

The AI Revelation

You see, I’ve found myself doing more frontend development than ever before, and I’m not a good frontend developer. So I relied on Cursor to write most of the code for me, and (as many others have experienced) it totally blew my mind 🤯

Cursor is just really, really good at TypeScript, React, and Tailwind. I’ve built a functioning and (if I don’t say so myself) good-looking SPA. It’s been a blast. As a “backend guy,” I feel like my world has opened up.

But this got me thinking… you know what else Cursor is really great at? Perhaps even better at?

👉 Interacting with CRUD APIs.

While there’s tons of frontend training data for LLMs, there’s just as much (if not more) training data for CRUD lifecycle operations. They’ve also ingested all of Kubernetes, Terraform, Pulumi, SST, and the AWS CDK’s training data. Modern LLMs know it very well.

Long story short, I discovered that Cursor can pretty much one-shot the implementation of resources. All the resources in Alchemy are entirely generated on-demand (5-minute time investment, tops). When I run into a bug, I just explain it to Cursor, who fixes it immediately.

Working this way may seem like more work at first glance, but in practice, I think it’s not. I will never get blocked working this way. I will never have to wait for another person to prioritize my problem, merge a fix, and release the change. I will never be confused about what’s actually happening under the covers.

This is a game changer for me. It means we don’t need tools like Terraform to build layers of “provider” suites for us. We just need the engine, the bit that tracks state and decides what to create, update, or delete. The rest can be generated at near-zero cost.

Why This Changes Everything

I suspect a lot of people will push back on this claim of “zero cost” because they haven’t yet embraced the AI-generation workflow. Their instinct is right, but outdated.

Before LLMs, I would have agreed that this was infeasible, but I think we’ve finally crossed the threshold where LLMs can do this work trivially and respond in real-time to your requirements.

If this isn’t obvious to you, then I suggest forcing yourself to practice with AI code generation. When it messes up, try blaming yourself instead of blaming and discarding the LLM. I think you’re missing a skill.

This is why adoption curves are a thing. Do you want to be a laggard?

At the end of the day, you need to realize that agency is going to matter more and more as time progresses, and shackling yourself to a mega-provider who doesn’t even know your name is a ticket to inefficiency.

I think we’ve mostly been hoodwinked into thinking that because managing infrastructure is complicated, we need complicated solutions. Now is the time for that pendulum to swing back in the other direction and “un-bundle” IaC.