Skip to content

Document raw Containers API alongside Container class - #33093

Open
thomasgauvin wants to merge 2 commits into
productionfrom
codex/container-api-docs
Open

Document raw Containers API alongside Container class#33093
thomasgauvin wants to merge 2 commits into
productionfrom
codex/container-api-docs

Conversation

@thomasgauvin

Copy link
Copy Markdown
Contributor

Summary

Documents two ways to interact with Containers:

  • Recommends the Durable Object Container API (ctx.container) for direct lifecycle control.
  • Keeps the higher-level Container class as an optional convenience layer.
  • Adds an API comparison and container lifecycle diagram.
  • Moves both API references into the Containers docs.
  • Adds raw API variants to examples, listed before Container class variants.
  • Adds Wrangler configuration documentation.
  • Updates navigation, links, and redirects.

Testing

  • pnpm run check
  • Redirect validation
  • Type-checked the new raw API examples against Workers types
  • git diff --check

@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Review

✅ No issues found in commit 83a920b.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

No code review issues found.

Conventions

No convention issues found.

Style Guide Review

No style-guide issues found.

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command Description
/review Runs a review now. Incremental if a prior review exists, full if not.
/full-review Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

@github-actions github-actions Bot added product:workers Related to Workers product product:reference-architecture product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ product:changelog product:containers product:sandbox size/xl labels Aug 28, 2026
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 28, 2026

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://codex-container-api-docs.previews.developers.cloudflare.com (commit 83a920b)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://9a798b9b.previews.developers.cloudflare.com 83a920b 2026-08-28T19:54:16.489Z Visit the dashboard ↗
  • Build: In progress 🔵

View logs ↗
c4d901b 2026-08-28T19:38:04.123Z View logs ↗

@github-actions

Copy link
Copy Markdown
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/public/__redirects @cloudflare/content-engineering, @cloudflare/product-owners
/src/content/changelog/ @cloudflare/pm-changelogs, @cloudflare/product-owners
/src/content/docs/containers/ @mikenomitch, @th0m, @cloudflare/product-owners, @cloudflare/cloudchamber
/src/content/docs/durable-objects/ @rita3ko, @irvinebroque, @vy-ton, @iglesiasbrandon, @joshthoward, @danlapid, @lambrospetrou, @mikenomitch, @cloudflare/product-owners
/src/content/docs/reference-architecture/ @securitypedant, @cloudflare/product-owners, @ncrouch-cflare
/src/content/docs/sandbox/ @cloudflare/product-owners, @cloudflare/ai-agents
/src/content/docs/workers/wrangler/ @cloudflare/wrangler, @irvinebroque, @cloudflare/product-owners, @MattieTK, @vy-ton

@github-actions

Copy link
Copy Markdown
Contributor

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

  • /containers/reference/container-class/
  • /containers/guides/outbound-traffic/
  • /containers/examples/durable-object-interface/
  • /containers/reference/durable-object-methods/

@github-actions

Copy link
Copy Markdown
Contributor

Preview URL: https://83a920be.preview.developers.cloudflare.com
Preview Branch URL: https://codex-container-api-docs.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/containers/api/durable-object-container/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/api/durable-object-container/
https://developers.cloudflare.com/durable-objects/api/container/ https://codex-container-api-docs.preview.developers.cloudflare.com/durable-objects/api/container/
https://developers.cloudflare.com/containers/examples/env-vars-and-secrets/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/env-vars-and-secrets/
https://developers.cloudflare.com/containers/api/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/api/
https://developers.cloudflare.com/containers/examples/cron/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/cron/
https://developers.cloudflare.com/containers/examples/r2-fuse-mount/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/r2-fuse-mount/
https://developers.cloudflare.com/containers/examples/status-hooks/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/status-hooks/
https://developers.cloudflare.com/containers/configuration/wrangler/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/configuration/wrangler/
https://developers.cloudflare.com/containers/examples/container-backend/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/container-backend/
https://developers.cloudflare.com/containers/examples/stateless/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/stateless/
https://developers.cloudflare.com/containers/examples/websocket/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/websocket/
https://developers.cloudflare.com/containers/concepts/architecture/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/concepts/architecture/
https://developers.cloudflare.com/containers/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/
https://developers.cloudflare.com/containers/examples/durable-object-interface/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/examples/durable-object-interface/
https://developers.cloudflare.com/containers/api/container-class/ https://codex-container-api-docs.preview.developers.cloudflare.com/containers/api/container-class/

end
```

A Container can only be accessed through its Durable Object. A Worker sends a request to the Durable Object, which accesses the Container through `ctx.container`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Durable Object" could link to (https://developers.cloudflare.com/durable-objects/) so people & agents starting here can learn about the Durable Object execution model

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

product:changelog product:containers product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ product:reference-architecture product:sandbox product:workers Related to Workers product size/xl

Projects

None yet

Development

Successfully merging this pull request may close these issues.