Skip to content

secondsky/claude-skills / plugins/cloudflare-durable-objects/skills/cloudflare-durable-objects

cloudflare-durable-objects

Verified

Cloudflare Durable Objects for stateful coordination and real-time apps. Use for chat, multiplayer games, WebSocket hibernation, or encountering class export, migration, alarm errors.

FileKindSize
SKILL.mdskill md21.6 KB
references/advanced-sql-patterns.mdmarkdown15.8 KB
references/alarms-api.mdmarkdown6.5 KB
references/best-practices.mdmarkdown8.5 KB
references/common-patterns.mdmarkdown16.7 KB
references/data-modeling.mdmarkdown16.9 KB
references/error-codes.mdmarkdown7.7 KB
references/gradual-deployments.mdmarkdown13.9 KB
references/migration-cheatsheet.mdmarkdown3.2 KB
references/migrations-guide.mdmarkdown7.3 KB
references/monitoring-debugging.mdmarkdown18.2 KB
references/performance-optimization.mdmarkdown16.2 KB
references/rpc-metadata.mdmarkdown16.9 KB
references/rpc-patterns.mdmarkdown6.5 KB
references/security-best-practices.mdmarkdown15.9 KB
references/state-api-reference.mdmarkdown6.0 KB
references/stubs-routing.mdmarkdown10.6 KB
references/top-errors.mdmarkdown10.2 KB
references/typescript-config.mdmarkdown8.3 KB
references/vitest-testing.mdmarkdown18.1 KB
references/websocket-hibernation.mdmarkdown6.3 KB
references/wrangler-commands.mdmarkdown3.4 KB
scripts/check-versions.shexecutablescript593 B
scripts/migration-generator.shexecutablescript13.4 KB
scripts/setup-vitest-do.shexecutablescript10.2 KB
scripts/validate-do-config.shexecutablescript10.0 KB
templates/alarms-api-do.tsscript6.1 KB
templates/basic-do.tsscript2.9 KB
templates/gradual-deployment-config.jsoncother10.4 KB
templates/location-hints.tsscript6.8 KB
templates/multi-do-coordination.tsscript7.8 KB
templates/package.jsonmanifest384 B
templates/rpc-metadata-do.tsscript10.8 KB
templates/rpc-vs-fetch.tsscript6.0 KB
templates/state-api-patterns.tsscript5.8 KB
templates/ttl-cleanup-do.tsscript17.6 KB
templates/vitest-do-test.tsscript12.3 KB
templates/websocket-hibernation-do.tsscript6.0 KB
templates/wrangler-do-config.jsoncother2.0 KB

references/migration-cheatsheet.md

View on GitHub
# Durable Objects Migration Cheatsheet

**Status**: Production Ready ✅
**Last Verified**: 2025-12-27

Quick reference guide for Durable Objects migrations.

---

## Migration Types

### New Class (SQL Backend)

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["Counter"]
    }
  ]
}
```

### New Class (KV Backend - Legacy)

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["Counter"]
    }
  ]
}
```

### Rename Class

```jsonc
{
  "migrations": [
    {
      "tag": "v2",
      "renamed_classes": [
        { "from": "Counter", "to": "GlobalCounter" }
      ]
    }
  ]
}
```

### Delete Class

```jsonc
{
  "migrations": [
    {
      "tag": "v3",
      "deleted_classes": ["OldCounter"]
    }
  ]
}
```

### Transfer Class

```jsonc
{
  "migrations": [
    {
      "tag": "v4",
      "transferred_classes": [
        {
          "from": "Counter",
          "from_script": "old-worker",
          "to": "Counter",
          "to_script": "new-worker"
        }
      ]
    }
  ]
}
```

---

## Common Migration Patterns

### Adding New DO to Existing Project

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["Counter"]
    },
    {
      "tag": "v2",  // New migration
      "new_sqlite_classes": ["ChatRoom"]
    }
  ]
}
```

### Switching from KV to SQL

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["Counter"]  // Started with KV
    },
    {
      "tag": "v2",
      "deleted_classes": ["Counter"]  // Delete KV version
    },
    {
      "tag": "v3",
      "new_sqlite_classes": ["Counter"]  // Create SQL version
    }
  ]
}
```

**Note**: Data is NOT automatically migrated. Implement custom migration logic if needed.

---

## Migration Validation

### Before Deployment

```bash
# Validate wrangler.jsonc
./scripts/validate-do-config.sh

# Check for common mistakes
jq '.migrations' wrangler.jsonc

# Verify class exports
grep -r "export.*Counter" src/
```

### Deployment

```bash
# Deploy atomically
wrangler deploy

# Check status
wrangler tail
```

### Rollback

```bash
# Restore backup
cp wrangler.jsonc.backup wrangler.jsonc

# Redeploy
wrangler deploy
```

---

## Common Mistakes

### ❌ Missing Migration for New Class

```jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  }
  // ❌ No migrations array
}
```

### ❌ Wrong Migration Type (KV vs SQL)

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["Counter"]  // ❌ Should be new_sqlite_classes
    }
  ]
}
```

### ❌ Non-Atomic Migration Tags

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["Counter"]
    },
    {
      "tag": "v1",  // ❌ Duplicate tag
      "new_sqlite_classes": ["ChatRoom"]
    }
  ]
}
```

---

## Migration Timeline

```
v1 → v2 → v3 → v4
```

**Rules**:
- Tags must be unique
- Migrations are applied in order
- Cannot skip versions
- Cannot modify past migrations

---

## Quick Commands

```bash
# Generate migration
./scripts/migration-generator.sh

# Validate config
./scripts/validate-do-config.sh

# Deploy
wrangler deploy

# Monitor
wrangler tail
```

---

**Last Updated**: 2025-12-27
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall