How to Publish Artifacts with the Cloudflare Artifacts Binding

To publish artifacts with the Cloudflare Artifacts binding, configure the binding in wrangler.toml, create a session-scoped client using createArtifact(), and use methods like createRepo() and add() to upload files to a Durable Object-backed artifact store.

The Cloudflare Artifacts binding provides a Durable Object-backed artifact store that functions like a private package registry within Workers. In the cloudflare/computer repository, this binding is wrapped by a first-class TypeScript API that enables session-scoped artifact management, allowing you to publish artifacts programmatically or via an integrated CLI.

Configure the Artifacts Binding

Before publishing, you must add an Artifacts binding to your Worker's configuration. This exposes the binding through the env object at runtime, making it available to your application code.

Add the following to your wrangler.toml:

[[artifacts]]
binding = "ARTIFACTS"

The binding name injected into env corresponds to the value specified in the configuration.

Create a Session-Scoped Client

The createArtifact helper function wraps the raw binding and automatically prefixes repository names with a session identifier. This isolation ensures that concurrent runs operate on distinct namespaces without collision, while your code works with short, local names only.

import { createArtifact } from "@cloudflare/computer/artifacts";

const sessionId = "my-run-123";
const client = createArtifact(env.ARTIFACTS, sessionId);

The client implementation resides in packages/computer/src/artifacts/client.ts, while the public API surface—including createArtifact and runArtifactsCLI—is exported from packages/computer/src/artifacts/index.ts.

Publish Artifacts Programmatically

Once instantiated, the client exposes methods to manage repositories and upload content. All repository names are automatically prefixed with your session ID.

Initialize a Repository

Create a repository using createRepo(). If the repository already exists, the operation handles the conflict gracefully depending on the binding's configuration.

await client.createRepo("my-artifact");

Upload Individual Files

Add files to a repository using the add() method, which accepts a path and content as a Uint8Array:

await client.add("my-artifact", {
  path: "index.js",
  content: new TextEncoder().encode('export default "hello";'),
});

Import Archives

For bulk operations, import entire directories from URLs or ZIP archives using import():

await client.import("my-artifact", {
  source: { url: "https://example.com/my-lib.zip" },
});

This method is particularly useful for publishing pre-built libraries or build artifacts.

Using the CLI Interface

The same implementation backs an in-shell CLI available in the worker-shell backend. The CLI driver is implemented in packages/computer/src/artifacts/cli.ts and exported as runArtifactsCLI. To integrate commands into a custom shell environment, use defineArtifactsCommand from packages/computer/src/backends/worker-shell/artifacts-command.ts:

import { defineArtifactsCommand } from "@cloudflare/computer/backends/worker-shell/artifacts-command";

const artifactsCmd = defineArtifactsCommand({
  artifacts: client,
  git: gitClient,
});
ws.shell.addCommand(artifactsCmd);

This guarantees that the programmatic API and the CLI stay in sync, as both consume the same underlying client logic.

Error Handling and Testing

The client defines specific error types in packages/computer/src/artifacts/errors.ts. Handle these exceptions to manage failure scenarios robustly:

• ArtifactError: Base error class for all artifact operations
• InvalidRepoNameError: Thrown when repository names violate naming constraints
• InvalidSessionIdError: Raised for malformed session identifiers
• NotFoundError: Indicates missing repositories or files

For unit testing, the repository provides FakeArtifactsBinding in packages/computer/tests/utilities/fake-artifacts-binding.ts. This in-memory implementation simulates the binding without requiring live Durable Objects, enabling fast, isolated tests.

Summary

• Configure the Artifacts binding in wrangler.toml to expose it via env.ARTIFACTS according to the Cloudflare Workers platform specification
• Use createArtifact() from @cloudflare/computer/artifacts to instantiate a session-scoped client that automatically isolates repositories by session ID, as implemented in packages/computer/src/artifacts/client.ts
• Publish content via createRepo(), add(), or import() methods to upload files or bulk-import archives
• Leverage the CLI interface through runArtifactsCLI or defineArtifactsCommand for shell-based workflows in the worker-shell backend
• Handle specific error types defined in packages/computer/src/artifacts/errors.ts for robust error management and debugging
• Test implementations using FakeArtifactsBinding without requiring live Durable Object infrastructure

Frequently Asked Questions

What is the Cloudflare Artifacts binding?

The Cloudflare Artifacts binding is a Workers platform feature that provides a Durable Object-backed storage system functioning as a private artifact registry. It allows Workers to create repositories, upload files, and manage versioned artifacts programmatically within the Cloudflare edge network.

How does session scoping work in the Artifacts client?

The createArtifact() helper automatically prefixes all repository names with the provided sessionId parameter. This creates an isolated namespace for each session, preventing naming collisions between concurrent runs while allowing the application code to use simple, local repository names without managing the prefixes manually.

Can I publish artifacts without using the Computer project wrapper?

While the raw Artifacts binding is a native Cloudflare platform feature, the cloudflare/computer project provides the createArtifact() wrapper, error handling, and CLI tooling in packages/computer/src/artifacts/. You can interact with the raw binding directly, but the Computer project's abstraction handles session management and provides a consistent TypeScript API surface.

What error types should I handle when publishing artifacts?

You should handle ArtifactError (the base class), InvalidRepoNameError (for naming violations), InvalidSessionIdError (for malformed session IDs), and NotFoundError (for missing resources). These are all defined in packages/computer/src/artifacts/errors.ts and provide specific context for implementing proper failure recovery logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}