Lifecycle

Deep dive into Alchemy’s resource lifecycle and deployment phases

Lifecycle

Alchemy manages infrastructure through a well-defined lifecycle that handles creation, updates, and deletion of resources. Understanding this lifecycle is essential for building reliable infrastructure.

Deployment Phases

Alchemy applications operate in one of three phases:

Up Phase (Default)

The up phase creates and updates resources:

bun ./alchemy.run.ts

const app = await alchemy("my-app", {
  phase: "up"  // Default, usually omitted
});

const worker = await Worker("api", {
  entrypoint: "./src/api.ts"
});
// Resource is created or updated

await app.finalize();

The up phase is the default. You typically don’t need to specify it explicitly.

Destroy Phase

The destroy phase deletes all resources:

bun ./alchemy.run.ts --destroy

const app = await alchemy("my-app", {
  phase: "destroy"
});

const worker = await Worker("api", {
  entrypoint: "./src/api.ts"
});
// Resource is deleted

await app.finalize();

Destroy phase permanently deletes infrastructure. Use with caution, especially in production.

Read Phase

The read phase retrieves resource state without making changes:

bun ./alchemy.run.ts --read

const app = await alchemy("my-app", {
  phase: "read"
});

const worker = await Worker("api", {
  entrypoint: "./src/api.ts"
});
// Returns existing resource from state
console.log(worker.url);
// No changes are made

await app.finalize();

Read phase is useful for inspecting deployed infrastructure or in multi-app deployments where one app depends on another.

Resource Lifecycle Phases

Individual resources go through their own lifecycle phases:

Create Phase

When a resource doesn’t exist in state:

export const MyResource = Resource(
  "provider::MyResource",
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    console.log("Phase:", this.phase); // "create"
    console.log("Output:", this.output); // undefined
    console.log("Props:", this.props); // undefined
    
    // Provision new infrastructure
    const result = await api.createResource({
      name: props.name,
      config: props.config
    });
    
    return {
      id,
      name: result.name,
      resourceId: result.id
    };
  }
);

1. Handler invoked

   Resource handler called with phase “create”

2. Infrastructure provisioned

   API calls create the actual infrastructure

3. State saved

   Return value is saved to state with status “created”

Update Phase

When resource exists but props have changed:

export const MyResource = Resource(
  "provider::MyResource",
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    if (this.phase === "update") {
      console.log("Previous output:", this.output);
      console.log("Previous props:", this.props);
      
      // Check for immutable property changes
      if (this.output.name !== props.name) {
        // Name is immutable - trigger replacement
        return this.replace();
      }
      
      // Update mutable properties
      const result = await api.updateResource(
        this.output.resourceId,
        { config: props.config }
      );
      
      return {
        id,
        name: this.output.name,
        resourceId: this.output.resourceId,
        config: result.config
      };
    }
    
    // Create logic...
  }
);

1. Props comparison

   Alchemy detects props have changed from state

2. Handler invoked

   Resource handler called with phase “update”

3. Infrastructure updated

   API calls update the existing infrastructure

4. State updated

   New state saved with old props preserved in oldProps

Delete Phase

When resource is removed from code or explicitly destroyed:

export const MyResource = Resource(
  "provider::MyResource",
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    if (this.phase === "delete") {
      console.log("Deleting:", this.output);
      
      // Clean up infrastructure
      try {
        await api.deleteResource(this.output.resourceId);
      } catch (error) {
        if (error.status !== 404) {
          throw error; // Re-throw unless already deleted
        }
      }
      
      // Signal deletion complete
      return this.destroy();
    }
    
    // Create/update logic...
  }
);

1. Orphan detection OR explicit destroy

   Resource exists in state but not in code, or app in destroy phase

2. Handler invoked

   Resource handler called with phase “delete”

3. Infrastructure deleted

   API calls remove the infrastructure

4. State removed

   this.destroy() deletes the state file

Always call this.destroy() in the delete phase. Without it, Alchemy won’t remove the state.

Lifecycle Transitions

First Deployment

const app = await alchemy("my-app");

const worker = await Worker("api", {
  entrypoint: "./src/api.ts"
});
// Phase: create
// Creates worker and saves state

await app.finalize();

State file created:

{
  "kind": "cloudflare::Worker",
  "id": "api",
  "status": "created",
  "props": { "entrypoint": "./src/api.ts" },
  "output": { "url": "https://api.worker.dev" }
}

Second Deployment (No Changes)

const app = await alchemy("my-app");

const worker = await Worker("api", {
  entrypoint: "./src/api.ts"
});
// Props unchanged - no update needed
// Returns existing state

await app.finalize();

If props haven’t changed, Alchemy skips the update unless --force is used.

Third Deployment (Props Changed)

const app = await alchemy("my-app");

const worker = await Worker("api", {
  entrypoint: "./src/api.ts",
  compatibilityFlags: ["nodejs_compat"]  // New prop
});
// Phase: update
// Updates worker with new config

await app.finalize();

State updated:

{
  "kind": "cloudflare::Worker",
  "id": "api",
  "status": "updated",
  "props": { 
    "entrypoint": "./src/api.ts",
    "compatibilityFlags": ["nodejs_compat"]
  },
  "oldProps": { "entrypoint": "./src/api.ts" },
  "output": { "url": "https://api.worker.dev" }
}

Fourth Deployment (Resource Removed)

const app = await alchemy("my-app");

// Worker not created anymore

await app.finalize();
// Orphan detected: "api" exists in state but not in code
// Phase: delete
// Worker destroyed and state removed

Resource Replacement

Some changes require replacing a resource entirely:

export const MyResource = Resource(
  "provider::MyResource",
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    // Check for immutable property changes
    if (this.phase === "update" && this.output.region !== props.region) {
      // Region can't be changed - must recreate
      return this.replace();
    }
    
    // Normal create/update logic
  }
);

Replacement workflow:

1. Detect immutable change

   this.replace() is called during update phase

2. Mark for replacement

   Old resource is added to pending deletions

3. Create new resource

   Handler is called again in “create” phase with isReplacement: true

4. Delete old resource

   After new resource succeeds, old resource is destroyed

5. Update state

   State points to new resource

Replacement causes downtime as the old resource is deleted before the new one is fully ready.

Finalization

The finalization process runs after all resources are created:

const app = await alchemy("my-app");

// Create resources
const worker = await Worker("api", { ... });
const bucket = await R2Bucket("storage", { ... });

// Finalize - critical step!
await app.finalize();

Finalization steps:

1. Execute deferred operations

   Operations registered with scope.defer() run

2. Finalize child scopes

   Recursively finalize nested scopes

3. Detect orphaned resources

   Compare state with resources created in code

4. Destroy pending deletions

   Delete resources marked for replacement

5. Destroy orphans

   Delete resources no longer in code

6. Run cleanup handlers

   Execute functions registered with scope.onCleanup()

Forgetting await app.finalize() means orphaned resources won’t be cleaned up!

Deferred Operations

Defer operations until finalization:

const app = await alchemy("my-app");

const worker = await Worker("api", { ... });

// Defer operation until finalization
const result = app.defer(async () => {
  // This runs during app.finalize()
  const response = await fetch(worker.url);
  return response.text();
});

await app.finalize();

// Now the deferred operation has completed
const text = await result;
console.log(text);

Deferred operations are useful for post-deployment validations or setup that requires all resources to exist.

Cleanup Handlers

Register cleanup for process exit:

const app = await alchemy("my-app");

await alchemy.run("dev-server", async (scope) => {
  const server = await startServer();
  
  // Register cleanup
  scope.onCleanup(async () => {
    console.log("Shutting down server...");
    await server.close();
  });
});

await app.finalize();

// When process exits (Ctrl+C, etc.):
// - Cleanup handlers run
// - Server is gracefully shut down

Destroy Strategies

Control how resources are destroyed:

Sequential (Default)

Destroy resources one at a time:

const app = await alchemy("my-app", {
  destroyStrategy: "sequential"
});

Parallel

Destroy all resources concurrently:

const app = await alchemy("my-app", {
  destroyStrategy: "parallel"
});

Per-Resource Strategy

Override strategy for specific resources:

export const MyResource = Resource(
  "provider::MyResource",
  { destroyStrategy: "parallel" },
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    // Implementation
  }
);

Sequential is safer but slower. Parallel is faster but may cause issues if resources have dependencies.

Force Mode

Force updates even when props haven’t changed:

bun ./alchemy.run.ts --force

const app = await alchemy("my-app", {
  force: true
});

Use cases:

• Recover from state corruption
• Apply provider-side changes
• Debug update logic

Adoption

Adopt existing resources:

bun ./alchemy.run.ts --adopt

const app = await alchemy("my-app", {
  adopt: true
});

const worker = await Worker("existing-worker", {
  name: "my-existing-worker"
});
// If worker exists: adopts it
// If worker doesn't exist: creates it

Adoption is useful for migrating existing infrastructure to Alchemy management.

Error Handling

Handling errors during lifecycle:

export const MyResource = Resource(
  "provider::MyResource",
  async function (this: Context<MyResource>, id: string, props: MyResourceProps) {
    if (this.phase === "delete") {
      try {
        await api.deleteResource(this.output.resourceId);
      } catch (error) {
        // Handle deletion errors gracefully
        if (error.status === 404) {
          // Already deleted - OK
        } else if (error.message.includes("in use")) {
          // Resource is in use - warn but continue
          console.warn(`Resource ${id} still in use, skipping deletion`);
        } else {
          // Unexpected error - fail
          throw error;
        }
      }
      
      return this.destroy();
    }
    
    // Create/update logic
  }
);

Best Practices

1. Handle all phases

   Implement create, update, and delete logic completely

2. Validate immutability

   Call this.replace() when immutable properties change

3. Graceful deletion

   Handle 404 errors during deletion (resource already gone)

4. Always finalize

   Call await app.finalize() to clean up orphans

5. Use deferred operations

   Defer post-deployment tasks until all resources exist

6. Register cleanups

   Use scope.onCleanup() for process exit handlers

Next Steps

Resources

Implement resources with proper lifecycle handling

State Management

Understand how state drives the lifecycle

Scopes

Manage scope-level lifecycle and finalization

Deployment

Deploy infrastructure using lifecycle phases