Add support for Images binding (#7945)

* Add Images binding

* Add Images remote preview mode

* Plumb images local mode flag through

* Add Images binding local mode

* Add Images E2E test

* Hoist @img packages

This fixes the fixture tests, perhaps because sharp does something
unusual with imports, see GH comment: nuxt/image#1210 (comment)

* Add local suffix when printing bindings

* Swap describe/it in E2E test

* Mark sharp as unbundled, rather than hoisting

* Remove zod

* Improve error messages

Author: ns476

.changeset/beige-chicken-sort.md

@@ -0,0 +1,5 @@
+---
+"wrangler": minor
+---
+
+Add Images binding (in private beta for the time being)

packages/wrangler/e2e/dev-with-resources.test.ts

@@ -720,6 +720,40 @@ describe.sequential.each(RUNTIMES)("Bindings: $flags", ({ runtime, flags }) => {
 		await expect(res.text()).resolves.toBe("env.WORKFLOW is available");
 	});
 
+	describe.sequential.each([
+		{ imagesMode: "remote", extraFlags: "" },
+		{ imagesMode: "local", extraFlags: "--experimental-images-local-mode" },
+	] as const)("Images Binding Mode: $imagesMode", async ({ extraFlags }) => {
+		it("exposes Images bindings", async () => {
+			await helper.seed({
+				"wrangler.toml": dedent`
+					name = "my-images-demo"
+					main = "src/index.ts"
+					compatibility_date = "2024-12-27"
+
+					[images]
+					binding = "IMAGES"
+				`,
+				"src/index.ts": dedent`
+					export default {
+						async fetch(request, env, ctx) {
+							if (env.IMAGES === undefined) {
+								return new Response("env.IMAGES is undefined");
+							}
+
+							return new Response("env.IMAGES is available");
+						}
+					}
+				`,
+			});
+			const worker = helper.runLongLived(`wrangler dev ${flags} ${extraFlags}`);
+			const { url } = await worker.waitForReady();
+			const res = await fetch(url);
+
+			await expect(res.text()).resolves.toBe("env.IMAGES is available");
+		});
+	});
+
 	// TODO(soon): implement E2E tests for other bindings
 	it.skipIf(isLocal).todo("exposes send email bindings");
 	it.skipIf(isLocal).todo("exposes browser bindings");

packages/wrangler/package.json

@@ -76,6 +76,7 @@
 		"esbuild": "0.17.19",
 		"miniflare": "workspace:*",
 		"path-to-regexp": "6.3.0",
+		"sharp": "^0.33.5",
 		"unenv": "2.0.0-rc.1",
 		"workerd": "1.20250124.0"
 	},

packages/wrangler/scripts/deps.ts

@@ -38,6 +38,9 @@ export const EXTERNAL_DEPENDENCIES = [
 
 	// workerd contains a native binary, so must be external. Wrangler depends on a pinned version.
 	"workerd",
+
+	// sharp contains native libraries
+	"sharp",
 ];
 
 const pathToPackageJson = path.resolve(__dirname, "..", "package.json");

packages/wrangler/src/__tests__/config/configuration.test.ts

@@ -2302,6 +2302,69 @@ describe("normalizeAndValidateConfig()", () => {
 			});
 		});
 
+		// Images
+		describe("[images]", () => {
+			it("should error if images is an array", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ images: [] } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+			"Processing wrangler configuration:
+			  - The field \\"images\\" should be an object but got []."
+		`);
+			});
+
+			it("should error if images is a string", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ images: "BAD" } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+			"Processing wrangler configuration:
+			  - The field \\"images\\" should be an object but got \\"BAD\\"."
+		`);
+			});
+
+			it("should error if images is a number", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ images: 999 } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+			"Processing wrangler configuration:
+			  - The field \\"images\\" should be an object but got 999."
+		`);
+			});
+
+			it("should error if ai is null", () => {
+				const { diagnostics } = normalizeAndValidateConfig(
+					{ images: null } as unknown as RawConfig,
+					undefined,
+					undefined,
+					{ env: undefined }
+				);
+
+				expect(diagnostics.hasWarnings()).toBe(false);
+				expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+			"Processing wrangler configuration:
+			  - The field \\"images\\" should be an object but got null."
+		`);
+			});
+		});
+
 		// Worker Version Metadata
 		describe("[version_metadata]", () => {
 			it("should error if version_metadata is an array", () => {

packages/wrangler/src/__tests__/deploy.test.ts

@@ -11903,6 +11903,37 @@ export default{
 		});
 	});
 
+	describe("images", () => {
+		it("should upload images bindings", async () => {
+			writeWranglerConfig({
+				images: { binding: "IMAGES_BIND" },
+			});
+			await fs.promises.writeFile("index.js", `export default {};`);
+			mockSubDomainRequest();
+			mockUploadWorkerRequest({
+				expectedBindings: [
+					{
+						type: "images",
+						name: "IMAGES_BIND",
+					},
+				],
+			});
+
+			await runWrangler("deploy index.js");
+			expect(std.out).toMatchInlineSnapshot(`
+				"Total Upload: xx KiB / gzip: xx KiB
+				Worker Startup Time: 100 ms
+				Your worker has access to the following bindings:
+				- Images:
+				  - Name: IMAGES_BIND
+				Uploaded test-name (TIMINGS)
+				Deployed test-name triggers (TIMINGS)
+				  https://test-name.test-sub-domain.workers.dev
+				Current Version ID: Galaxy-Class"
+			`);
+		});
+	});
+
 	describe("python", () => {
 		it("should upload python module defined in wrangler.toml", async () => {
 			writeWranglerConfig({

packages/wrangler/src/__tests__/dev.test.ts

@@ -1399,7 +1399,8 @@ describe.sequential("wrangler dev", () => {
 				      --test-scheduled                             Test scheduled events by visiting /__scheduled in browser  [boolean] [default: false]
 				      --log-level                                  Specify logging level  [choices: \\"debug\\", \\"info\\", \\"log\\", \\"warn\\", \\"error\\", \\"none\\"] [default: \\"log\\"]
 				      --show-interactive-dev-session               Show interactive dev session (defaults to true if the terminal supports interactivity)  [boolean]
-				      --experimental-vectorize-bind-to-prod        Bind to production Vectorize indexes in local development mode  [boolean] [default: false]",
+				      --experimental-vectorize-bind-to-prod        Bind to production Vectorize indexes in local development mode  [boolean] [default: false]
+				      --experimental-images-local-mode             Use a local lower-fidelity implementation of the Images binding  [boolean] [default: false]",
 				  "warn": "",
 				}
 			`);

packages/wrangler/src/__tests__/pages/pages.test.ts

@@ -77,7 +77,8 @@ describe("pages", () => {
 			      --persist-to                                 Specify directory to use for local persistence (defaults to .wrangler/state)  [string]
 			      --log-level                                  Specify logging level  [choices: \\"debug\\", \\"info\\", \\"log\\", \\"warn\\", \\"error\\", \\"none\\"]
 			      --show-interactive-dev-session               Show interactive dev session (defaults to true if the terminal supports interactivity)  [boolean]
-			      --experimental-vectorize-bind-to-prod        Bind to production Vectorize indexes in local development mode  [boolean] [default: false]"
+			      --experimental-vectorize-bind-to-prod        Bind to production Vectorize indexes in local development mode  [boolean] [default: false]
+			      --experimental-images-local-mode             Use a local lower-fidelity implementation of the Images binding  [boolean] [default: false]"
 		`);
 	});
 

packages/wrangler/src/__tests__/type-generation.test.ts

@@ -163,6 +163,9 @@ const bindingsConfigMock: Omit<
 	ai: {
 		binding: "AI_BINDING",
 	},
+	images: {
+		binding: "IMAGES_BINDING",
+	},
 	version_metadata: {
 		binding: "VERSION_METADATA_BINDING",
 	},

packages/wrangler/src/api/dev.ts

@@ -82,6 +82,7 @@ export interface Unstable_DevOptions {
 		devEnv?: boolean;
 		fileBasedRegistry?: boolean;
 		vectorizeBindToProd?: boolean;
+		imagesLocalMode?: boolean;
 		enableIpc?: boolean;
 	};
 }
@@ -126,6 +127,7 @@ export async function unstable_dev(
 		testMode,
 		testScheduled,
 		vectorizeBindToProd,
+		imagesLocalMode,
 		// 2. options for alpha/beta products/libs
 		d1Databases,
 		enablePagesAssetsServiceBinding,
@@ -218,6 +220,7 @@ export async function unstable_dev(
 		port: options?.port ?? 0,
 		experimentalProvision: undefined,
 		experimentalVectorizeBindToProd: vectorizeBindToProd ?? false,
+		experimentalImagesLocalMode: imagesLocalMode ?? false,
 		enableIpc: options?.experimental?.enableIpc,
 	};