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.

   This token must be the same for all deployments on your Cloudflare account.

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

   Use the Alchemy CLI to deploy and create the state store worker:

   bun

   bun alchemy deploy

   npm

   npx alchemy deploy

   pnpm

   pnpm alchemy deploy

   yarn

   yarn alchemy deploy

   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, {
    scriptName: "my-app-state-prod"
  })
});

Custom Token

Override the environment variable token:

const app = await alchemy("my-app", {
  stateStore: (scope) => new DOStateStore(scope, {
    stateToken: alchemy.secret(process.env.CUSTOM_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, {
    forceUpdate: 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, {
    scriptName: `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.