Part 1: Your First Stack

In this first part you’ll install Alchemy and Effect, create a Stack with an AWS S3 Bucket, and deploy it — all in under five minutes.

Prerequisites

• Bun or Node.js 24.11.1+
• An AWS account and an IAM identity with permission to create the resources you plan to deploy

Create a project

Start with an empty directory and initialize a package.json:

pnpm

mkdir my-app && cd my-app && pnpm init

bun

mkdir my-app && cd my-app && bun init -y

npm

mkdir my-app && cd my-app && npm init -y

yarn

mkdir my-app && cd my-app && yarn init -y

Install dependencies

Install alchemy@latest and effect:

pnpm

pnpm add alchemy@latest effect @effect/platform-bun @effect/platform-node

bun

bun add alchemy@latest effect @effect/platform-bun @effect/platform-node

npm

npm install alchemy@latest effect @effect/platform-bun @effect/platform-node

yarn

yarn add alchemy@latest effect @effect/platform-bun @effect/platform-node

Create the Stack

Every Alchemy program starts with a Stack — a collection of Resources managed by Providers with state tracked between deploys.

Create an alchemy.run.ts file:

alchemy.run.ts

import * as Alchemy from "alchemy";
import * as AWS from "alchemy/AWS";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyApp",
  {
    providers: AWS.providers(),
    state: AWS.state(),
  },
  Effect.gen(function* () {
    // we'll add resources here next
  }),
);

Alchemy.Stack is the root of every app. The first argument ("MyApp") doubles as a logical id and as the prefix Alchemy uses when AWS asks for physical resource names.

How credentials resolve

providers: AWS.providers() registers every AWS resource and IAM policy binding that ships with Alchemy, and resolves credentials from your Alchemy profile. Connect SSO or stored access keys with alchemy profile edit --add AWS. See Setup for the details of each method.

Where state lives

state: AWS.state() stores deploy state in an account-regional S3 bucket (alchemy-state-{accountId}-{region}-an), created lazily on the first deploy. Because the state lives in your AWS account rather than on disk, the same configuration works locally and in CI with no extra setup.

Other state stores

For purely local iteration you can use Alchemy.localState() instead, which writes state under .alchemy/ next to your code — or write your own.

Add a Resource

Resources represent cloud infrastructure — buckets, tables, queues, functions, and so on. Each resource is yield*-ed inside the Stack’s Effect generator.

Add an S3 Bucket:

alchemy.run.ts

import * as Alchemy from "alchemy";
import * as AWS from "alchemy/AWS";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyApp",
  {
    providers: AWS.providers(),
    state: AWS.state(),
  },
  Effect.gen(function* () {
    const bucket = yield* AWS.S3.Bucket("Bucket");
  }),
);

yield* AWS.S3.Bucket("Bucket") registers the resource with the Stack under the logical id Bucket and returns a typed Bucket handle. We didn’t pass a bucketName, so Alchemy generates a unique physical name from the app, stage, and logical id.

Return Stack outputs

Stack outputs let you see important values after a deploy. Return an object from the generator to expose them:

Effect.gen(function* () {
  const bucket = yield* AWS.S3.Bucket("Bucket");

  return {
    bucketName: bucket.bucketName,
  };
}),

bucket.bucketName is an Output — a typed reference to an attribute the cloud will produce. It resolves during deploy and prints with the rest of the stack outputs.

Deploy

Run alchemy deploy to create the Bucket on AWS:

pnpm

pnpm alchemy deploy

bun

bun alchemy deploy

npm

npx alchemy deploy

yarn

yarn alchemy deploy

Connect AWS first with alchemy profile edit --add AWS and pick a local authentication method: SSO (recommended), console login (aws login), or stored access keys. The choice is saved to your default profile; the region and account come from whichever method you pick, and a deploy with nothing configured fails with that exact command to run. CI instead reads AWS environment credentials directly. See Setup for the full walkthrough.

Tip

To re-run the credential prompt later (e.g. to switch from stored keys to SSO or console login), use alchemy profile edit --reconfigure AWS. For a separate profile, run alchemy profile create prod followed by alchemy profile edit --profile prod.

Plan: 1 to create
+ Bucket (AWS.S3.Bucket)

Proceed?
◉ Yes ○ No
✓ Bucket (AWS.S3.Bucket) created
{
  bucketName: "myapp-bucket-a1b2c3d4e5",
}

Alchemy shows a plan, asks for confirmation, creates the resource, and prints the stack outputs. Your bucket is live on AWS.

Tip

By convention, Alchemy looks for alchemy.run.ts at the root of your project. You can specify a different file with alchemy deploy --config <file>.

Verify it worked

Your newly created bucket will be listed in the S3 section of the AWS Console (or via aws s3 ls if you have the AWS CLI installed).

Run alchemy deploy again. Because nothing changed, the bucket shows as a no-op:

Plan: no changes

{
  bucketName: "myapp-bucket-a1b2c3d4e5",
}

This is the core loop — declare resources in code, deploy, and Alchemy figures out what changed.

Destroy (optional)

The inverse of deploy is destroy — it plans against an empty desired state and deletes everything the stack created:

bun alchemy destroy

Try it if you like, then run bun alchemy deploy again to bring the bucket back — we’ll build on it in Part 2.

Recap

You now have:

• An alchemy.run.ts with a Stack and an AWS S3 Bucket
• A live bucket deployed to your AWS account
• Stack outputs showing the bucket name

In Part 2, you’ll add a Lambda Function with a public URL that reads and writes objects in this bucket.