All Posts
2025-01-20

Alchemy: Reimagining Infrastructure as Code with TypeScript

AWSIaCAlchemyDevOpsTypeScript
A

Infrastructure as Code (IaC) has evolved significantly, but tools like AWS CDK and Terraform often introduce layers of complexity with custom state management, heavy CLIs, and specific domain languages. Alchemy takes a different approach: it reimagines infrastructure as pure, composable TypeScript code.

In this post, we'll explore Alchemy, its philosophy, and how to deploy your first AWS resource using it.

What is Alchemy?

Alchemy is a lightweight IaC toolkit created by Sam Goodwin. Unlike traditional tools that require complex engines (like the JVM for CDK or the Go runtime for Terraform), Alchemy is designed to be a library you import, not a framework that controls you.

It communicates directly with cloud service APIs (like AWS, Cloudflare) using standard HTTPS requests, eliminating the need for intermediate translation layers like CloudFormation.

The Philosophy: Zero Dependencies

The core philosophy of Alchemy is "Zero Dependencies". It aims to make infrastructure feel like importing a module and writing a function.

  • No heavy CLI: You run it with standard TypeScript runtimes like bun or node.
  • Direct API calls: It wraps AWS APIs in clean, async functions.
  • Composable: Resources are just functions you can compose and reuse.

Getting Started with Alchemy

Let's dive into a practical example. We will create a simple S3 bucket using Alchemy and bun.

Prerequisites

Ensure you have Bun installed and your AWS credentials configured in your environment.

1. Initialize the Project

Create a new directory and initialize a Bun project:

mkdir alchemy-demo
cd alchemy-demo
bun init -y

Rename the entry file to follow Alchemy's convention:

mv index.ts alchemy.run.ts

2. Install Alchemy

Add the Alchemy package to your project:

bun add alchemy

3. Write the Infrastructure Code

Open alchemy.run.ts and add the following code. This script defines an application and an S3 bucket.

import alchemy from 'alchemy';
import { Bucket } from 'alchemy/aws';

// Define the stage (e.g., dev, prod)
const stage = process.env.STAGE || 'dev';

// Initialize the Alchemy app
const app = await alchemy('app', {
    stage,
    phase: process.argv.includes('--destroy') ? 'destroy' : 'up',
});

// Define an S3 Bucket resource
const bucket = await Bucket('bucket', {
    bucketName: `alchemy-demo-bucket-${stage}`,
});

// Finalize the application state
await app.finalize();

This code is straightforward TypeScript. We import the Bucket resource, define it with a name, and Alchemy handles the lifecycle.

Deploying to AWS

To deploy your infrastructure, simply execute the script with Bun:

bun alchemy.run.ts

You should see output indicating the resource creation:

Create:  "app/dev/bucket"
Created: "app/dev/bucket"

If you check your AWS Console, you'll find the new S3 bucket ready for use.

Cleaning Up

One of the best features is how easy it is to tear down the environment. Just pass the destroy flag we handled in the code:

bun alchemy.run.ts --destroy

Output:

Delete:  "app/dev/bucket"
Deleted: "app/dev/bucket"

Conclusion

Alchemy represents a shift towards simpler, more developer-centric infrastructure tools. By leveraging standard language features and direct API interactions, it removes the "black box" magic of traditional IaC tools.

If you are interested in modern infrastructure approaches, check out our AWS Consultancy and Kubernetes Consultancy services.

Frequently Asked Questions (FAQ)

1. How does Alchemy manage state?

Alchemy uses a pluggable state management system. By default, it can store state locally or in cloud storage, tracking resource lifecycles transparently without complex backend configurations.

2. Is Alchemy production-ready?

Alchemy is a newer tool. While it offers a great developer experience, you should evaluate its maturity and community support before migrating large-scale production workloads.

3. Can I use Alchemy with other cloud providers?

Yes, Alchemy is designed to be extensible. While AWS is a primary focus, its architecture supports other providers like Cloudflare and GitHub by wrapping their APIs in similar resource functions.

Source: https://awsfundamentals.com/blog/alchemy-reimagining-iac