From 86dba8a3a0a3fdc010c6fdd9fcd329e25d15416c Mon Sep 17 00:00:00 2001 From: Leo Ostera Date: Thu, 8 Oct 2026 14:32:26 +0100 Subject: [PATCH 1/6] docs(artifacts): add local simulator development guide --- .../docs/artifacts/api/git-protocol.mdx | 6 +- .../docs/artifacts/api/workers-binding.mdx | 4 +- .../docs/artifacts/get-started/workers.mdx | 41 +++++---- .../docs/artifacts/guides/authentication.mdx | 4 +- src/content/docs/artifacts/guides/index.mdx | 2 +- .../artifacts/guides/local-development.mdx | 84 +++++++++++++++++++ 6 files changed, 111 insertions(+), 30 deletions(-) create mode 100644 src/content/docs/artifacts/guides/local-development.mdx diff --git a/src/content/docs/artifacts/api/git-protocol.mdx b/src/content/docs/artifacts/api/git-protocol.mdx index 0b2fe497d27..e590705b2b7 100644 --- a/src/content/docs/artifacts/api/git-protocol.mdx +++ b/src/content/docs/artifacts/api/git-protocol.mdx @@ -10,9 +10,9 @@ products: Artifacts exposes Git access for every Artifacts repository. -Each repo has a standard Git smart HTTP remote at `https://.artifacts.cloudflare.net/git//.git`. +Each deployed repo has a standard Git smart HTTP remote at `https://.artifacts.cloudflare.net/git//.git`. -Replace the `` placeholder with your Cloudflare account ID. Use the exact hostname from the repo `remote` returned by the Workers binding or REST API. +Replace the `` placeholder with your Cloudflare account ID. A local Artifacts binding instead returns an HTTP loopback URL with a dev-session port. Use the exact `remote` returned by the Workers binding or REST API, and refer to [Local development](/artifacts/guides/local-development/) for local setup. Use the returned repo `remote` with a regular Git client for `clone`, `fetch`, `pull`, and `push`. @@ -27,7 +27,7 @@ Git routes accept repo access tokens in two forms: ### Token format -Repo tokens are issued in the format `art_v1_<40 hex>?expires=`. The `?expires=` suffix is the token's expiry as a unix timestamp in seconds. To check when a token expires, parse the value after `?expires=`. +Use the complete token returned by Artifacts for Bearer authentication. Tokens include an `?expires=` suffix with their expiry as a Unix timestamp in seconds. Do not assume a fixed token prefix or secret length. For HTTP Basic authentication, use only the portion before `?expires=` as the password. ### Git `extraHeader` parameter diff --git a/src/content/docs/artifacts/api/workers-binding.mdx b/src/content/docs/artifacts/api/workers-binding.mdx index b44858c8d48..b05ba303a49 100644 --- a/src/content/docs/artifacts/api/workers-binding.mdx +++ b/src/content/docs/artifacts/api/workers-binding.mdx @@ -33,7 +33,7 @@ Add the Artifacts binding to your Wrangler config file: [[artifacts]] binding = "ARTIFACTS" namespace = "default" # replace with your Artifacts namespace -# remote = true # optional: use the remote Artifacts service in local dev +# Set remote = true to use deployed Artifacts during local development. ``` @@ -46,7 +46,7 @@ export interface Env { } ``` -Wrangler generates the `Artifacts` type for consumers and binds it directly in your environment. +Wrangler generates the `Artifacts` type for consumers and binds it directly in your environment. In local development, omitting `remote` or setting `remote = false` uses the local simulator. Set `remote = true` to reach the deployed service. For the local Git prerequisite, storage boundaries, and setup instructions, refer to [Local development](/artifacts/guides/local-development/). :::note diff --git a/src/content/docs/artifacts/get-started/workers.mdx b/src/content/docs/artifacts/get-started/workers.mdx index 69fe5b12f84..fb349b97550 100644 --- a/src/content/docs/artifacts/get-started/workers.mdx +++ b/src/content/docs/artifacts/get-started/workers.mdx @@ -40,10 +40,10 @@ To set up Artifacts manually, follow the steps below. You also need: -- Wrangler installed. If you use local Wrangler commands in this guide, authenticate Wrangler first. For local OAuth authentication or CI setup, refer to [`wrangler login`](/workers/wrangler/commands/general/#login) and [Running Wrangler in CI/CD](/workers/ci-cd/). -- Access to Artifacts in your Cloudflare account. +- Wrangler installed. Local Artifacts development does not require Cloudflare credentials. Authenticate Wrangler before deploying or using a remote binding. +- Access to Artifacts in your Cloudflare account for the deployment step. - A namespace name, for example `default`. -- A local `git` client. +- Git installed on your development machine and available on `PATH`. The local simulator checks this at startup. - `jq`, if you want to extract response fields automatically. ## 1. Create a Worker project @@ -89,12 +89,12 @@ compatibility_date = "$today" [[artifacts]] binding = "ARTIFACTS" namespace = "default" -# Set remote = true if you want Wrangler to use the remote Artifacts service in local dev. +# To use deployed Artifacts during local development, set remote = true. ``` -This exposes Artifacts as `env.ARTIFACTS` inside your Worker. +This exposes Artifacts as `env.ARTIFACTS` inside your Worker. During local development, an omitted `remote` setting uses local storage. Set `remote = true` only if you want to use deployed Artifacts. Local and deployed repos do not synchronize. For prerequisites, persistence, and migration from implicit remote bindings, refer to [Local development](/artifacts/guides/local-development/). If you are using TypeScript, regenerate your local binding types: @@ -172,19 +172,20 @@ Your Worker will call `env.ARTIFACTS.create()` and return three values you will ```json { "name": "starter-repo", - "remote": "https://.artifacts.cloudflare.net/git/default/starter-repo.git", - "token": "art_v1_0123456789abcdef0123456789abcdef01234567?expires=1760000000" + "remote": "http://127.0.0.1:/git/default/starter-repo.git", + "token": "" } ``` - `name`: the repo name. Must be unique within the namespace. -- `remote`: the Git remote URL for this repo. `` will be your actual Cloudflare account ID. -- `token`: a short-lived credential for Git operations. The token encodes its expiry directly in the `?expires=` suffix as a Unix timestamp. +- `remote`: the local Git URL. Use the returned port rather than copying the placeholder. A deployed Worker instead returns an HTTPS URL for your account. +- `token`: a repo-scoped credential for Git operations. Keep its full value private. Copy the `remote` and `token` values into local shell variables: ```sh export ARTIFACTS_REMOTE="" -export ARTIFACTS_TOKEN="" +read -rs ARTIFACTS_TOKEN # Paste the token without saving it in your shell history. +printf '\n' ``` @@ -221,13 +222,7 @@ git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin The `-c http.extraHeader` flag passes the token as a request header, which keeps it out of your Git config and shell history. -If you need a self-contained remote URL for a short-lived command, build one from the token secret instead: - -```sh -export ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}" -export ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}" -git push "$ARTIFACTS_AUTH_REMOTE" HEAD:main -``` +For other authentication options, refer to [Git protocol](/artifacts/api/git-protocol/). ## 6. Pull the repo with a regular Git client @@ -241,11 +236,7 @@ git -C artifacts-clone log --oneline -1 You should see the commit you pushed in the previous step. -You can also clone with a self-contained remote URL for a short-lived command: - -```sh -git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone -``` +Use the `remote` URL returned by your Worker after each dev-server restart. The local loopback port can change. ## 7. Deploy your Worker @@ -262,6 +253,12 @@ Wrangler prints your `workers.dev` URL. Use the same `curl` request against that ## Next steps + + **Read** for read routes and **Artifacts** > **Edit** for write routes. | Control-plane HTTP requests | | Git protocol | Repo-scoped Artifacts token | `read` for clone, fetch, and pull. `write` for push. | Standard Git over HTTPS | @@ -44,7 +44,7 @@ namespace = "default" -At runtime, deployed Workers use the configured binding directly. For local Wrangler commands such as `wrangler dev`, `wrangler deploy`, or `wrangler types`, authenticate Wrangler first. For local OAuth authentication, refer to [`wrangler login`](/workers/wrangler/commands/general/#login). For CI or headless environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/). +At runtime, deployed Workers use the configured binding directly. `wrangler dev` with a local Artifacts binding does not require Cloudflare credentials. To deploy or use `remote = true` during development, authenticate Wrangler. For OAuth authentication, refer to [`wrangler login`](/workers/wrangler/commands/general/#login). For CI or headless environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/). For the local Git prerequisite, refer to [Local development](/artifacts/guides/local-development/). ## Authenticate the REST API diff --git a/src/content/docs/artifacts/guides/index.mdx b/src/content/docs/artifacts/guides/index.mdx index 333936d43ed..8e515da555b 100644 --- a/src/content/docs/artifacts/guides/index.mdx +++ b/src/content/docs/artifacts/guides/index.mdx @@ -12,6 +12,6 @@ products: import { DirectoryListing } from "~/components"; -In-depth guides for using Artifacts in production, including how Artifacts authenticates clients, imports existing Git repos, and mounts large repos within sandboxes. +Guides for local development and deployed Artifacts, including authentication, imports, and mounting large repos within sandboxes. diff --git a/src/content/docs/artifacts/guides/local-development.mdx b/src/content/docs/artifacts/guides/local-development.mdx new file mode 100644 index 00000000000..a8e1cf5042c --- /dev/null +++ b/src/content/docs/artifacts/guides/local-development.mdx @@ -0,0 +1,84 @@ +--- +title: Develop with local Artifacts +description: Use the local Artifacts binding with Wrangler, Vite, or Workers Vitest without accessing your deployed repositories. +pcx_content_type: how-to +sidebar: + order: 1 +products: + - artifacts +--- + +import { PackageManagers, Steps, WranglerConfig } from "~/components"; + +The local Artifacts simulator lets you develop against a Git-compatible repository on your machine. Local repositories and tokens are separate from deployed Artifacts resources. Creating, pushing to, or deleting a local repo does not change a deployed repo. + +## Choose a binding mode + +When you run a Worker locally, the `artifacts` binding uses the local simulator unless you explicitly set `remote = true`. An omitted `remote` setting and `remote = false` both select local storage. If your existing development workflow relied on an implicit remote binding, set `remote = true` to keep using the deployed service. + +| Setting | Binding destination | Local Git installation | Cloudflare credentials for local development | +| --- | --- | --- | --- | +| Omitted `remote` or `remote = false` | Local simulator | Required | Not required | +| `remote = true` | Deployed Artifacts service | Not required to start the binding | Required | + +The local simulator is available through `wrangler dev`, the Cloudflare Vite plugin, and Workers Vitest. It does not provide a local REST API, Artifacts CLI, dashboard, SSH endpoint, or Git LFS server. + +## Start local development + + + +1. Install Git on your development machine. Make `git` available on the `PATH` of the process that starts your dev server or tests. Verify the installation in that environment: + + ```sh + git --version + ``` + + Local Artifacts checks Git during startup. If Git is unavailable, startup fails with installation instructions. Restart your dev tool after changing `PATH`. This first version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future; it is not included in this version. Deployed Artifacts does not require Git on your development machine. + +2. Add a binding to your Wrangler config file. If your project already has a binding, leave `remote` unset or set it to `false`: + + + + ```toml title="wrangler.toml" + name = "artifacts-worker" + main = "src/index.ts" + compatibility_date = "$today" + + [[artifacts]] + binding = "ARTIFACTS" + namespace = "default" + ``` + + + + The namespace identifies local repositories. It does not import repos from a deployed namespace with the same name. + +3. Start the dev server: + + + + Use the same Wrangler config file with the Cloudflare Vite plugin or Workers Vitest. For a Worker example that creates a repo, refer to [Get started with Workers](/artifacts/get-started/workers/). + +4. Use the `remote` URL and initial token returned by `env.ARTIFACTS.create()` to clone or push with Git. The local URL uses loopback HTTP and a port selected for this dev session. Get a fresh URL from the binding after restarting the dev server instead of hardcoding the port: + + ```sh + git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone + ``` + + Set `ARTIFACTS_REMOTE` to the returned `remote` value and `ARTIFACTS_TOKEN` to the returned token before running this command. The token is a repo credential, not a Cloudflare API token. Keep it out of source files, Git config, and logs. You can also use HTTP Basic auth when Git prompts: enter any username and the repo token as the password. + + + +## Keep or reset local repositories + +Local repository metadata and Git objects persist under your dev tool's resource persistence directory. For Wrangler, this is typically `.wrangler/state/` when persistence is on. Use the same project root and persistence settings to keep data across restarts. Turning off persistence, such as with Vite's `persistState: false`, makes the data temporary. + +To reset local Artifacts, stop the dev server and back up any repositories you need. Then delete only the `artifacts/` directory inside that tool's resource persistence directory. Do not delete unrelated binding data. Local tokens and repository data do not transfer to a remote binding. + +## Use an HTTPS import explicitly + +Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git contacts the host named in that URL. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification. + +A successful local import does not retain URL credentials in repository metadata or the Git configuration. If the process exits during an import, treat any partial local storage as sensitive until you inspect or reset it. Keep import URLs with credentials out of logs. For the binding arguments, refer to [Workers binding](/artifacts/api/workers-binding/#importparams). + +To use deployed Artifacts during local development, set `remote = true` on the binding and authenticate your dev tool. The remote binding does not synchronize with the local simulator. For authentication options, refer to [Authentication](/artifacts/guides/authentication/). From aa626d187ba3e351f429cb8104b1ace85ebf8393 Mon Sep 17 00:00:00 2001 From: Leo Ostera Date: Thu, 8 Oct 2026 16:08:25 +0100 Subject: [PATCH 2/6] docs(artifacts): clarify local HTTPS import boundaries --- src/content/docs/artifacts/guides/local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/artifacts/guides/local-development.mdx b/src/content/docs/artifacts/guides/local-development.mdx index a8e1cf5042c..d9132d37663 100644 --- a/src/content/docs/artifacts/guides/local-development.mdx +++ b/src/content/docs/artifacts/guides/local-development.mdx @@ -77,7 +77,7 @@ To reset local Artifacts, stop the dev server and back up any repositories you n ## Use an HTTPS import explicitly -Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git contacts the host named in that URL. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification. +Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git on your development machine contacts the specified host, including private-network hosts. Only import URLs you trust. Imports do not follow HTTP redirects; supply the final HTTPS Git URL, especially when using credentials. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification. A successful local import does not retain URL credentials in repository metadata or the Git configuration. If the process exits during an import, treat any partial local storage as sensitive until you inspect or reset it. Keep import URLs with credentials out of logs. For the binding arguments, refer to [Workers binding](/artifacts/api/workers-binding/#importparams). From 48a8d253754787ef1995e15939b73afc9c548e47 Mon Sep 17 00:00:00 2001 From: Leo Ostera Date: Thu, 8 Oct 2026 16:50:10 +0100 Subject: [PATCH 3/6] docs(artifacts): require Git 2.32 for local development --- src/content/docs/artifacts/get-started/workers.mdx | 6 +++--- .../docs/artifacts/guides/local-development.mdx | 14 ++++++++------ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/src/content/docs/artifacts/get-started/workers.mdx b/src/content/docs/artifacts/get-started/workers.mdx index fb349b97550..590f3de47b2 100644 --- a/src/content/docs/artifacts/get-started/workers.mdx +++ b/src/content/docs/artifacts/get-started/workers.mdx @@ -43,7 +43,7 @@ You also need: - Wrangler installed. Local Artifacts development does not require Cloudflare credentials. Authenticate Wrangler before deploying or using a remote binding. - Access to Artifacts in your Cloudflare account for the deployment step. - A namespace name, for example `default`. -- Git installed on your development machine and available on `PATH`. The local simulator checks this at startup. +- Git 2.32 or newer installed on your development machine and available on `PATH`. The local simulator checks the Git version at startup. - `jq`, if you want to extract response fields automatically. ## 1. Create a Worker project @@ -208,7 +208,6 @@ export ARTIFACTS_TOKEN=$(printf '%s' "$RESPONSE" | jq -r '.token') In the previous step, your Worker created an empty Artifacts repo. Now you will create a local Git repo, add a file, and push it to Artifacts — the same way you would push to any Git remote. - ```sh mkdir artifacts-demo cd artifacts-demo @@ -240,7 +239,8 @@ Use the `remote` URL returned by your Worker after each dev-server restart. The ## 7. Deploy your Worker -Switch back to your Worker project directory: +Switch back to your Worker project directory: + ```sh cd artifacts-worker ``` diff --git a/src/content/docs/artifacts/guides/local-development.mdx b/src/content/docs/artifacts/guides/local-development.mdx index d9132d37663..49edef60441 100644 --- a/src/content/docs/artifacts/guides/local-development.mdx +++ b/src/content/docs/artifacts/guides/local-development.mdx @@ -16,10 +16,10 @@ The local Artifacts simulator lets you develop against a Git-compatible reposito When you run a Worker locally, the `artifacts` binding uses the local simulator unless you explicitly set `remote = true`. An omitted `remote` setting and `remote = false` both select local storage. If your existing development workflow relied on an implicit remote binding, set `remote = true` to keep using the deployed service. -| Setting | Binding destination | Local Git installation | Cloudflare credentials for local development | -| --- | --- | --- | --- | -| Omitted `remote` or `remote = false` | Local simulator | Required | Not required | -| `remote = true` | Deployed Artifacts service | Not required to start the binding | Required | +| Setting | Binding destination | Local Git installation | Cloudflare credentials for local development | +| ------------------------------------ | -------------------------- | --------------------------------- | -------------------------------------------- | +| Omitted `remote` or `remote = false` | Local simulator | Required | Not required | +| `remote = true` | Deployed Artifacts service | Not required to start the binding | Required | The local simulator is available through `wrangler dev`, the Cloudflare Vite plugin, and Workers Vitest. It does not provide a local REST API, Artifacts CLI, dashboard, SSH endpoint, or Git LFS server. @@ -27,13 +27,15 @@ The local simulator is available through `wrangler dev`, the Cloudflare Vite plu -1. Install Git on your development machine. Make `git` available on the `PATH` of the process that starts your dev server or tests. Verify the installation in that environment: +1. Install Git 2.32 or newer on your development machine. Make `git` available on the `PATH` of the process that starts your dev server or tests. Verify the version in that environment: ```sh git --version ``` - Local Artifacts checks Git during startup. If Git is unavailable, startup fails with installation instructions. Restart your dev tool after changing `PATH`. This first version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future; it is not included in this version. Deployed Artifacts does not require Git on your development machine. + Use an up-to-date, security-patched Git release. + + If Git is unavailable or older than 2.32, local Artifacts fails at startup with installation or upgrade instructions. Restart your dev tool after changing `PATH`. This version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future; it is not included in this version. Deployed Artifacts does not require Git on your development machine. 2. Add a binding to your Wrangler config file. If your project already has a binding, leave `remote` unset or set it to `false`: From 5d5b72013ad7da4fa6d7719fc40152de4a5a404b Mon Sep 17 00:00:00 2001 From: Leo Ostera Date: Tue, 13 Oct 2026 20:25:50 +0100 Subject: [PATCH 4/6] docs(artifacts): split local development guidance sentences --- src/content/docs/artifacts/guides/local-development.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/artifacts/guides/local-development.mdx b/src/content/docs/artifacts/guides/local-development.mdx index 49edef60441..18fbb1f1e66 100644 --- a/src/content/docs/artifacts/guides/local-development.mdx +++ b/src/content/docs/artifacts/guides/local-development.mdx @@ -35,7 +35,7 @@ The local simulator is available through `wrangler dev`, the Cloudflare Vite plu Use an up-to-date, security-patched Git release. - If Git is unavailable or older than 2.32, local Artifacts fails at startup with installation or upgrade instructions. Restart your dev tool after changing `PATH`. This version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future; it is not included in this version. Deployed Artifacts does not require Git on your development machine. + If Git is unavailable or older than 2.32, local Artifacts fails at startup with installation or upgrade instructions. Restart your dev tool after changing `PATH`. This version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future. It is not included in this version. Deployed Artifacts does not require Git on your development machine. 2. Add a binding to your Wrangler config file. If your project already has a binding, leave `remote` unset or set it to `false`: @@ -79,7 +79,7 @@ To reset local Artifacts, stop the dev server and back up any repositories you n ## Use an HTTPS import explicitly -Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git on your development machine contacts the specified host, including private-network hosts. Only import URLs you trust. Imports do not follow HTTP redirects; supply the final HTTPS Git URL, especially when using credentials. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification. +Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git on your development machine contacts the specified host, including private-network hosts. Only import URLs you trust. Imports do not follow HTTP redirects. Supply the final HTTPS Git URL, especially when using credentials. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification. A successful local import does not retain URL credentials in repository metadata or the Git configuration. If the process exits during an import, treat any partial local storage as sensitive until you inspect or reset it. Keep import URLs with credentials out of logs. For the binding arguments, refer to [Workers binding](/artifacts/api/workers-binding/#importparams). From fb8099d328d45cb7ae81059adf798f6e74bc38e9 Mon Sep 17 00:00:00 2001 From: Leo Ostera Date: Wed, 14 Oct 2026 11:06:38 +0100 Subject: [PATCH 5/6] docs(artifacts): add local development changelog entry --- ...2026-10-14-local-artifacts-development.mdx | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx diff --git a/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx b/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx new file mode 100644 index 00000000000..9962faca0aa --- /dev/null +++ b/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx @@ -0,0 +1,27 @@ +--- +title: Develop with Artifacts locally +description: Create and test Artifacts repositories in Wrangler, Workers Vitest, and the Cloudflare Vite plugin. +products: + - artifacts +date: 2026-10-14 +--- + +import { WranglerConfig } from "~/components"; + +We are excited to bring Artifacts to local development! In `wrangler dev`, Workers Vitest, and the Cloudflare Vite plugin, you can create repos, import existing Git repositories over HTTPS, push commits, and test read and write tokens without deploying or changing your deployed repositories. + +To get started, add an Artifacts binding for your namespace: + + + +```toml title="wrangler.toml" +[[artifacts]] +binding = "ARTIFACTS" +namespace = "default" +``` + + + +Make sure Git 2.32 or newer is installed and available on your `PATH`. The binding uses local storage by default. If your development setup already uses deployed Artifacts, set `remote = true` to keep that behavior. + +For setup and persistence details, refer to [Local development](/artifacts/guides/local-development/). From dc480920873f10721037f592741d77fae0cdbe9d Mon Sep 17 00:00:00 2001 From: dkozlov Date: Wed, 14 Oct 2026 11:36:25 -0400 Subject: [PATCH 6/6] [Artifacts] Align local development changelog with local dev announcements --- ...2026-10-14-local-artifacts-development.mdx | 38 +++++++++++++++---- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx b/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx index 9962faca0aa..40e3c59c07e 100644 --- a/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx +++ b/src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx @@ -1,20 +1,25 @@ --- -title: Develop with Artifacts locally -description: Create and test Artifacts repositories in Wrangler, Workers Vitest, and the Cloudflare Vite plugin. +title: Artifacts now supports local development +description: Create, import, clone, and push Artifacts repos locally with Wrangler, the Cloudflare Vite plugin, and Workers Vitest. products: - artifacts + - workers date: 2026-10-14 --- -import { WranglerConfig } from "~/components"; +import { TypeScriptExample, WranglerConfig } from "~/components"; -We are excited to bring Artifacts to local development! In `wrangler dev`, Workers Vitest, and the Cloudflare Vite plugin, you can create repos, import existing Git repositories over HTTPS, push commits, and test read and write tokens without deploying or changing your deployed repositories. +You can now develop and test [Artifacts](/artifacts/) locally using `npx wrangler dev`, the [Cloudflare Vite plugin](/workers/vite-plugin/), and the [Workers Vitest integration](/workers/testing/vitest-integration/). Create repos, import Git repositories over HTTPS, issue repo tokens, and clone or push with Git on your machine before deploying to Cloudflare's global network. Local repos are separate from your deployed repos, so you can test changes without affecting production data. -To get started, add an Artifacts binding for your namespace: +Artifacts bindings now use a local simulator by default: -```toml title="wrangler.toml" +```toml +name = "artifacts-worker" +main = "src/index.ts" +compatibility_date = "$today" + [[artifacts]] binding = "ARTIFACTS" namespace = "default" @@ -22,6 +27,23 @@ namespace = "default" -Make sure Git 2.32 or newer is installed and available on your `PATH`. The binding uses local storage by default. If your development setup already uses deployed Artifacts, set `remote = true` to keep that behavior. +Then use the binding the same way you would in production: + + + +```ts +const created = await env.ARTIFACTS.create("starter-repo"); + +return Response.json({ + remote: created.remote, + token: created.token, +}); +``` + + + +The returned `remote` points to your local dev session, so you can use it with a standard Git client to clone and push. + +Local development requires Git 2.32 or later on your `PATH`. If you already use deployed Artifacts during local development, set `remote = true` on the binding to keep that behavior. -For setup and persistence details, refer to [Local development](/artifacts/guides/local-development/). +To get started, refer to [Local development](/artifacts/guides/local-development/).