feat: add artifacts binding support to wrangler

Add wrangler configuration, deployment, and type generation support
for the Artifacts binding (git-compatible file storage).

Config (workers-utils):
- environment.ts: add artifacts binding option
- validation.ts: add validateArtifactsBinding validator
- config.ts: add default empty array
- types.ts: add artifacts binding type
- worker.ts: add CfArtifacts interface
- map-worker-metadata-bindings.ts: handle artifacts type

Wrangler:
- create-worker-upload-form.ts: serialize artifacts bindings
- bindings.ts: pass through artifacts config
- type-generation/index.ts: generate Artifacts type reference
- print-bindings.ts: display artifacts bindings
- dev.ts, start-dev.ts: wire up artifacts config
- dev/miniflare/index.ts: pass to miniflare
- api/startDevWorker/utils.ts: handle artifacts binding type
- secret/index.ts: include in empty bindings
- add-created-resource-config.ts: include in resource types

Binding config example:
  { "artifacts": [{ "binding": "MY_ARTIFACTS", "namespace": "default" }] }

Type generation produces: MY_ARTIFACTS: Artifacts

Ref: cloudflare/ai-agents/artifacts#4

Author: mattzcarey

packages/workers-utils/src/config/config.ts

@@ -329,6 +329,7 @@ export const defaultWranglerConfig: Config = {
 	hyperdrive: [],
 	workflows: [],
 	secrets_store_secrets: [],
+	artifacts: [],
 	services: [],
 	analytics_engine_datasets: [],
 	ai: undefined,

packages/workers-utils/src/config/environment.ts

@@ -1230,6 +1230,24 @@ export interface EnvironmentNonInheritable {
 		secret_name: string;
 	}[];
 
+	/**
+	 * Specifies Artifacts bindings that are bound to this Worker environment.
+	 * Artifacts provides git-compatible file storage on Cloudflare Workers.
+	 *
+	 * NOTE: This field is not automatically inherited from the top level environment,
+	 * and so must be specified in every named environment.
+	 *
+	 * @default []
+	 * @nonInheritable
+	 */
+	artifacts: {
+		/** The binding name used to refer to the Artifacts instance. */
+		binding: string;
+
+		/** The namespace to use. Defaults to "default" if not specified. */
+		namespace?: string;
+	}[];
+
 	/**
 	 * **DO NOT USE**. Hello World Binding Config to serve as an explanatory example.
 	 *

packages/workers-utils/src/config/validation.ts

@@ -95,6 +95,7 @@ export const friendlyBindingNames: Record<
 	workflows: "Workflow",
 	pipelines: "Pipeline",
 	secrets_store_secrets: "Secrets Store Secret",
+	artifacts: "Artifacts",
 	ratelimits: "Rate Limit",
 	assets: "Assets",
 	unsafe_hello_world: "Hello World",
@@ -1714,6 +1715,16 @@ function normalizeAndValidateEnvironment(
 			validateBindingArray(envName, validateSecretsStoreSecretBinding),
 			[]
 		),
+		artifacts: notInheritable(
+			diagnostics,
+			topLevelEnv,
+			rawConfig,
+			rawEnv,
+			envName,
+			"artifacts",
+			validateBindingArray(envName, validateArtifactsBinding),
+			[]
+		),
 		unsafe_hello_world: notInheritable(
 			diagnostics,
 			topLevelEnv,
@@ -4276,6 +4287,44 @@ const validateSecretsStoreSecretBinding: ValidatorFn = (
 	return isValid;
 };
 
+const validateArtifactsBinding: ValidatorFn = (
+	diagnostics,
+	field,
+	value
+) => {
+	if (typeof value !== "object" || value === null) {
+		diagnostics.errors.push(
+			`"artifacts" bindings should be objects, but got ${JSON.stringify(value)}`
+		);
+		return false;
+	}
+	let isValid = true;
+	if (!isRequiredProperty(value, "binding", "string")) {
+		diagnostics.errors.push(
+			`"${field}" bindings must have a string "binding" field but got ${JSON.stringify(
+				value
+			)}.`
+		);
+		isValid = false;
+	}
+
+	if ("namespace" in value && typeof value.namespace !== "string") {
+		diagnostics.errors.push(
+			`"${field}" bindings "namespace" field must be a string but got ${JSON.stringify(
+				value.namespace
+			)}.`
+		);
+		isValid = false;
+	}
+
+	validateAdditionalProperties(diagnostics, field, Object.keys(value), [
+		"binding",
+		"namespace",
+	]);
+
+	return isValid;
+};
+
 const validateHelloWorldBinding: ValidatorFn = (diagnostics, field, value) => {
 	if (typeof value !== "object" || value === null) {
 		diagnostics.errors.push(

packages/workers-utils/src/map-worker-metadata-bindings.ts

@@ -125,6 +125,19 @@ export function mapWorkerMetadataBindings(
 							];
 						}
 						break;
+					case "artifacts":
+						{
+							configObj.artifacts = [
+								...(configObj.artifacts ?? []),
+								{
+									binding: binding.name,
+									...(binding.namespace !== undefined && {
+										namespace: binding.namespace,
+									}),
+								},
+							];
+						}
+						break;
 					case "unsafe_hello_world": {
 						configObj.unsafe_hello_world = [
 							...(configObj.unsafe_hello_world ?? []),

packages/workers-utils/src/types.ts

@@ -115,6 +115,11 @@ export type WorkerMetadataBinding =
 			store_id: string;
 			secret_name: string;
 	  }
+	| {
+			type: "artifacts";
+			name: string;
+			namespace?: string;
+	  }
 	| {
 			type: "unsafe_hello_world";
 			name: string;

packages/workers-utils/src/worker.ts

@@ -225,6 +225,11 @@ export interface CfSecretsStoreSecrets {
 	secret_name: string;
 }
 
+export interface CfArtifacts {
+	binding: string;
+	namespace?: string;
+}
+
 export interface CfHelloWorld {
 	binding: string;
 	enable_timer?: boolean;
@@ -422,6 +427,7 @@ export interface CfWorkerInit {
 		vectorize: CfVectorize[] | undefined;
 		hyperdrive: CfHyperdrive[] | undefined;
 		secrets_store_secrets: CfSecretsStoreSecrets[] | undefined;
+		artifacts: CfArtifacts[] | undefined;
 		services: CfService[] | undefined;
 		vpc_services: CfVpcService[] | undefined;
 		analytics_engine_datasets: CfAnalyticsEngineDataset[] | undefined;

packages/wrangler/src/api/startDevWorker/utils.ts

@@ -280,6 +280,12 @@ export function convertCfWorkerInitBindingsToBindings(
 				}
 				break;
 			}
+			case "artifacts": {
+				for (const { binding, ...x } of info) {
+					output[binding] = { type: "artifacts", ...x };
+				}
+				break;
+			}
 			case "unsafe_hello_world": {
 				for (const { binding, ...x } of info) {
 					output[binding] = { type: "unsafe_hello_world", ...x };
@@ -357,6 +363,7 @@ export async function convertBindingsToCfWorkerInitBindings(
 		vectorize: undefined,
 		hyperdrive: undefined,
 		secrets_store_secrets: undefined,
+		artifacts: undefined,
 		services: undefined,
 		vpc_services: undefined,
 		analytics_engine_datasets: undefined,
@@ -499,6 +506,9 @@ export async function convertBindingsToCfWorkerInitBindings(
 				...omitType(binding),
 				binding: name,
 			});
+		} else if (binding.type === "artifacts") {
+			bindings.artifacts ??= [];
+			bindings.artifacts.push({ ...omitType(binding), binding: name });
 		} else if (binding.type === "unsafe_hello_world") {
 			bindings.unsafe_hello_world ??= [];
 			bindings.unsafe_hello_world.push({ ...omitType(binding), binding: name });

packages/wrangler/src/deployment-bundle/bindings.ts

@@ -61,6 +61,7 @@ export function getBindings(
 		vectorize: config?.vectorize,
 		hyperdrive: config?.hyperdrive,
 		secrets_store_secrets: config?.secrets_store_secrets,
+		artifacts: config?.artifacts,
 		services: config?.services,
 		analytics_engine_datasets: config?.analytics_engine_datasets,
 		dispatch_namespaces: options?.pages

packages/wrangler/src/deployment-bundle/create-worker-upload-form.ts

@@ -279,6 +279,14 @@ export function createWorkerUploadForm(
 		}
 	);
 
+	bindings.artifacts?.forEach(({ binding, namespace }) => {
+		metadataBindings.push({
+			name: binding,
+			type: "artifacts",
+			...(namespace !== undefined && { namespace }),
+		});
+	});
+
 	bindings.unsafe_hello_world?.forEach(({ binding, enable_timer }) => {
 		metadataBindings.push({
 			name: binding,

packages/wrangler/src/dev.ts

@@ -656,6 +656,7 @@ export function getBindings(
 		vectorize: configParam.vectorize,
 		hyperdrive: hyperdriveBindings,
 		secrets_store_secrets: configParam.secrets_store_secrets,
+		artifacts: configParam.artifacts,
 		services: mergedServiceBindings,
 		vpc_services: configParam.vpc_services,
 		analytics_engine_datasets: configParam.analytics_engine_datasets,