# How to Publish Artifacts with the Cloudflare Artifacts Binding

> Publish artifacts with Cloudflare Artifacts binding by configuring wrangler.toml, creating a client, and using methods to upload files to your durable object-backed store. Get started today.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-08

---

**To publish artifacts with the Cloudflare Artifacts binding, configure the binding in [`wrangler.toml`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/wrangler.toml):

```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.

```typescript
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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/artifacts/client.ts), while the public API surface—including `createArtifact` and `runArtifactsCLI`—is exported from [`packages/computer/src/artifacts/index.ts`](https://github.com/cloudflare/computer/blob/main/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.

```typescript
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`:

```typescript
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()`**:

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/backends/worker-shell/artifacts-command.ts):

```typescript
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/artifacts/errors.ts) and provide specific context for implementing proper failure recovery logic.