DOStateStore

DOStateStore provides a State Store using a Cloudflare Worker and a SQLite3 Durable Object.

1. Generate a state token

   Create a secure token for state store authentication:

   openssl rand -base64 32

   Copy the generated token - you’ll need it in the next step.

2. Set environment variables

   Add the token to your environment:

   .env

   ALCHEMY_STATE_TOKEN=your-generated-token-here

   Tip

   Store this token securely and don’t commit it to version control.

3. Configure DOStateStore

   Update your alchemy.run.ts to use cloud state storage:

   import alchemy from "alchemy";
   import { DOStateStore } from "alchemy/cloudflare";
   
   const app = await alchemy("my-app", {
     stateStore: (scope) => new DOStateStore(scope)
   });
   
   // Your resources here...
   
   await app.finalize();

4. Deploy your app

   Run your Alchemy script to create the state store worker:

   bun

   bun ./alchemy.run.ts

   npm

   npx tsx ./alchemy.run.ts

   pnpm

   pnpm tsx ./alchemy.run.ts

   yarn

   yarn tsx ./alchemy.run.ts

   Alchemy automatically creates an alchemy-state worker in your Cloudflare account.

5. Verify the state store

   Check your Cloudflare dashboard to see the deployed worker:

   https://dash.cloudflare.com/workers

   You should see an alchemy-state worker handling your application state.

Customization

Custom Worker Name

Change the worker name to avoid conflicts or organize by environment:

const app = await alchemy("my-app", {
  stateStore: (scope) => new DOStateStore(scope, {
    worker: {
      name: "my-app-state-prod"
    }
  })
});

Custom Token

Override the environment variable token:

const app = await alchemy("my-app", {
  stateStore: (scope) => new DOStateStore(scope, {
    worker: {
      name: "my-app-state",
      token: alchemy.secret(process.env.CUSTOM_STATE_TOKEN)
    }
  })
});

Use Existing Worker

Connect to a pre-deployed state store worker:

const app = await alchemy("my-app", {
  stateStore: (scope) => new DOStateStore(scope, {
    worker: {
      url: "https://my-state-store.my-subdomain.workers.dev",
      token: alchemy.secret(process.env.STATE_TOKEN)
    }
  })
});

Force Worker Recreation

Force the worker to be recreated even if it exists:

const app = await alchemy("my-app", {
  stateStore: (scope) => new DOStateStore(scope, {
    worker: {
      name: "my-app-state",
      force: true
    }
  })
});

Environment-Specific Configuration

Development

Use local filesystem for development, cloud for production:

const app = await alchemy("my-app", {
  stateStore: process.env.NODE_ENV === "production"
    ? (scope) => new DOStateStore(scope)
    : undefined // Uses default FileSystemStateStore
});

Per-Environment Workers

Use different workers for different environments:

const stage = process.env.STAGE ?? "dev";

const app = await alchemy("my-app", {
  stage,
  stateStore: (scope) => new DOStateStore(scope, {
    worker: {
      name: `my-app-state-${stage}`
    }
  })
});

Authentication Requirements

DOStateStore requires Cloudflare authentication. See the Cloudflare Auth Guide for setup options:

• API Token (recommended)
• OAuth via wrangler login
• Global API Key (legacy)

Tip

The same Cloudflare credentials used for other resources work with DOStateStore.

How It Works

1. Worker Creation: DOStateStore automatically deploys a Cloudflare Worker with Durable Objects
2. State Storage: Your application state is stored in Durable Objects for high performance
3. Authentication: All requests use your generated token for secure access
4. Automatic Management: The worker handles state operations (get, set, delete, list)

The generated worker appears in your Cloudflare dashboard and can be managed like any other worker.