Cloudflare.Artifacts reference

Namespace

Source: packages/cloudflare/src/Artifacts/Namespace.ts

A Cloudflare Artifacts namespace — the top-level container for Git-compatible versioned repositories. See the Artifacts launch post and Namespaces docs.

Cloudflare creates a namespace implicitly the first time a repo is created against it (through the REST API or the Worker binding), so the Alchemy “resource” is a thin binding marker with nothing to provision at deploy time. Cloudflare also offers an explicit POST /artifacts/namespaces route, needed only to pin a data-location jurisdiction; this marker does not call it. Repos themselves are typically created at runtime through the bound Artifacts API.

Unlike the other Worker-only bindings, an Artifacts namespace does not auto-bind when yielded — it always requires an explicit access level via ReadNamespace / WriteNamespace / ReadWriteNamespace.

Namespace: Declaring a Namespace

Default namespace (a unique physical name is generated)

const Repos = Cloudflare.Artifacts.Namespace("Repos");

Override the namespace name (2–63 chars)

const Repos = Cloudflare.Artifacts.Namespace("Repos", { namespace: "starter-repos" });

Namespace: Binding to a Worker

Wiring it into a Worker

export const Worker = Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  bindings: { Repos },
});

export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
//   { Repos: Artifacts }

Async-style worker

export default {
  async fetch(request: Request, env: WorkerEnv) {
    const repo = await env.Repos.create("starter-repo");
    return Response.json({ remote: repo.remote, token: repo.token });
  },
};

Effect-style worker (explicit access level)

const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
const repo = yield* artifacts.create("starter-repo", {
  setDefaultBranch: "main",
});

Effect-style worker reading history (read-only access)

const artifacts = yield* Cloudflare.Artifacts.ReadNamespace(Repos);
const repo = yield* artifacts.get("starter-repo");
const commits = yield* repo.log({ ref: "main", limit: 10 });
const readme = yield* repo.readFile({ ref: "main", path: "README.md" });

ReadWriteNamespace

Source: packages/cloudflare/src/Artifacts/ReadWriteNamespace.ts

Bind a Cloudflare Artifacts namespace (Namespace) to a Worker and obtain the Effect-native ReadWriteNamespaceClient (read + write: create / list / get / delete / import). Repos looked up with get carry the full RepoClient: history and file reads plus token and fork management.

ReadWriteNamespace: Creating repos and tokens

Create a repo inside a Worker

const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
const repo = yield* artifacts.create("starter-repo", {
  setDefaultBranch: "main",
});

Mint a short-lived read token for an existing repo

const repo = yield* artifacts.get("starter-repo");
const token = yield* repo.createToken("read", 3600);

ReadWriteNamespace: Reading history and files

List the latest commits on a branch

const repo = yield* artifacts.get("starter-repo");
const commits = yield* repo.log({ ref: "main", limit: 10 });
// [{ hash, treeHash, message, author, committer, parents, authoredAt, committedAt }]

Read a file at a ref

const file = yield* repo.readFile({ ref: "main", path: "README.md" });
if (file !== null) {
  const text = yield* Effect.promise(() => file.text());
}

Walk a commit’s tree

const commit = yield* repo.readCommit(hash);
const entries = commit ? yield* repo.readTree(commit.treeHash) : null;
const blob = entries?.find((e) => e.name === "data.json");
const bytes = blob ? yield* repo.readBlob(blob.hash) : null;

ReadWriteNamespace: Handling errors

const repo = yield* artifacts.get(name).pipe(
  Effect.catchTag("ArtifactsError", (e) =>
    e.code === "NOT_FOUND" ? Effect.succeed(undefined) : Effect.fail(e),
  ),
);