chore(docs): clarify local vs stage scope properties and some usage examples

[agcty]

Add documentation explaining the difference between local and stage properties in Alchemy scopes.

Key additions:

• Clarify that local and stage are independent properties
• Show CLI usage examples for different combinations
• Explain state isolation per stage
• Provide common conditional pattern for resource configuration
• Add warning against using environment variables to mimic stages

This resolves confusion around running local environments with different stages (e.g., bun alchemy dev --stage e2e for E2E testing vs bun alchemy dev for regular development).

🤖 Generated with Claude Code

[Mkassabov]

So the generated docs here are kind of wrong, and the whole E2E_MODE variable just adds confusion in our opinion.

I want to acknowledge that we are probably missing something in our docs here. Can you I guess clarify what your understand is. I feel like something is getting lost in translation by having claude make a change here.

[agcty]

@Mkassabov The main trouble I had was creating different resources for different use cases but using env variables instead of stages. This led Alchemy to create/update/delete resources unexpectedly, and while Alchemy was doing the right thing, it wasn't immediately clear to me why.

Here's an example that shows the issue with the env pattern:

import alchemy from "alchemy"
import { FileSystemStateStore } from "alchemy/state"
import { Exec } from "alchemy/os"

const app = await alchemy("test", {
  stateStore: scope => new FileSystemStateStore(scope),
})

// Using environment variable to switch between E2E and dev
if (app.local && process.env.E2E === "e2e") {
  await Exec("e2e-resource", { command: "echo 'E2E mode'" })
} else if (app.local) {
  await Exec("dev-resource", { command: "echo 'Dev mode'" })
}

await app.finalize()

If you run this:

# First run - creates dev-resource
$ bun alchemy.run.ts --dev --stage dev
[creating]  dev-resource Creating Resource...
[created]   dev-resource Created Resource

# Second run - deletes dev-resource!
$ E2E=e2e bun alchemy.run.ts --dev --stage dev
[creating]  e2e-resource Creating Resource...
[created]   e2e-resource Created Resource
[deleting]  dev-resource Deleting Resource...
[deleted]   dev-resource Deleted Resource

Both runs use --stage dev, so they share .alchemy/test/dev/. When the env variable changes which resources should exist, Alchemy sees dev-resource as orphaned and tears it down.

The "better" pattern imo is using app.stage instead of environment variables:

// Using stage parameter
if (app.local && app.stage === "e2e") {
  await Exec("e2e-resource", { command: "echo 'E2E mode'" })
} else if (app.local) {
  await Exec("dev-resource", { command: "echo 'Dev mode'" })
}

Now it works correctly:

$ bun alchemy.run.ts --dev --stage dev
[creating]  dev-resource Creating Resource...
[created]   dev-resource Created Resource

$ bun alchemy.run.ts --dev --stage e2e
[creating]  e2e-resource Creating Resource...
[created]   e2e-resource Created Resource
# No deletions - both coexist in separate state directories

Each stage gets its own state directory (.alchemy/test/dev/ and .alchemy/test/e2e/), so you can run dev and E2E simultaneously without conflicts. I think this pattern might be worth documenting since it's easy to reach for environment variables when you probably should be using stages.

[Mkassabov]

I think this pattern might be worth documenting since it's easy to reach for environment variables when you probably should be using stages.

@agcty reading your response the above quote stands out to me as the key issue.

I'll talk to the team today to get consensus. I'm currently leaning towards making all the guides explicitly telling you to run with a specific stage rather than assuming a "default" stage that way users are exposed to it and we have a good direction to point them to from our guides. As well as rewriting the stage docs to provide more advanced examples

Do you think that would've been a good enough solution to prevent you from running into this? I'm trying to trace your journey with alchemy to figure out where you missed stages so we can expose it to users following in your footsteps.

[agcty]

@Mkassabov Yes, that would make a lot of sense. My journey roughly was:

"Oh wow this is really easy setting up resources, so much simpler and more flexible than other frameworks",
"I wonder if it has all of the resources i need"
"Great, I can easily create a db in the cloud, I wonder how I can I can use alchemy to develop locally as well"
"Hmm some resources work local by default (cloudflare r2, hyperdrive, etc), I wonder what is automatic and what not"
"A postgres db I'll definitely have to set up myself locally, there's no way alchemy would know what I need"
"My stages name is dev and I am trying to develop right now but I need it to handle different cases, I guess I'll just use an env var?"

What made it slightly confusing is that I was doing all of this inside a large monorepo, reading both the monorepo docs and the stage docs simultaneously, while also opening PRs to improve resources, so I was juggling too much at once. If the docs were more explicit about stages and monorepos, with a couple of best-practice patterns, I think the experience would have been smoother. But I do want to mention that overall it was a very sane experience but best practices would definitely help.