State

Alchemy uses a transparent and pluggable state management system to track resource lifecycles and enable idempotent operations. It's designed to be simple, with multiple backend options ranging from local files to cloud storage.

What is State in Alchemy?

State in Alchemy consists of resource data that tracks the current status, properties, and outputs of each resource. By default, it's stored in JSON files in a .alchemy directory, organized by app and stage:

.alchemy/
  my-app/
    dev/
      my-resource.json
      my-other-resource.json

State File Structure

Each state file contains the full information about a resource:

{
  "provider": "service::ResourceName",
  "data": {},
  "status": "updated",
  "output": {
    "id": "resource-123",
    "name": "My Resource",
    "createdAt": 1679012345678
  },
  "props": {
    "name": "My Resource",
    "description": "This is a test resource"
  }
}

The state file includes:

• provider: The resource type identifier
• data: Internal provider-specific data
• status: Current lifecycle status (created, updated, deleted)
• output: The resource's current output values
• props: The resource's input properties

How Alchemy Uses State

Alchemy uses state to determine the appropriate action for each resource:

1. No state file: The resource is created
2. State exists + props unchanged: The resource is skipped
3. State exists + props changed: The resource is updated
4. Resource removed from code: The resource is deleted

This approach enables idempotent operations - running the same code multiple times produces the same result, avoiding duplicate resource creation.

State Location

By default, Alchemy stores state files in the .alchemy directory in your project root. This approach has several benefits:

• Transparency: State files are plain JSON and can be inspected and modified manually
• Versioning: State can be committed to source control with your code
• Portability: No external service dependencies required

State Inspection

State files can be directly inspected:

cat .alchemy/my-app/dev/my-resource.json

This transparency helps with debugging and understanding what Alchemy is doing.

Customizing State Storage

Alchemy supports multiple state storage backends. You can use the default file system store or integrate with cloud services like Cloudflare R2:

// Example with Cloudflare R2 state store
const app = await alchemy("my-app", {
  stage: "prod",
  phase: process.argv.includes("--destroy") ? "destroy" : "up",
  stateStore: (scope) => new R2RestStateStore(scope, {
    apiKey: alchemy.secret(process.env.CLOUDFLARE_API_KEY),
    email: process.env.CLOUDFLARE_EMAIL,
    bucketName: process.env.CLOUDFLARE_BUCKET_NAME!,
  })
});

TIP

Learn how to implement your own state storage in Custom State Stores Guide

Security and Secrets

State files may contain sensitive information. Alchemy provides a mechanism to encrypt sensitive values using the alchemy.secret() function:

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

await ApiResource("my-api", {
  key: apiKey
});

Secrets are encrypted in state files:

{
  "props": {
    "key": {
      "@secret": "Tgz3e/WAscu4U1oanm5S4YXH..."
    }
  }
}

IMPORTANT

Always use alchemy.secret() for sensitive values to prevent them from being stored in plain text.

NOTE

Learn more about secrets management in Concepts: Secrets