feat: --assets / config.assets to serve a folder of static assets

This adds support for defining `assets` in `wrangler.toml`. You can configure it with a string path, or a `{bucket, include, exclude}` object (much like `[site]`). This also renames the `--experimental-public` arg as `--assets`.

Via #1162

Author: threepointone

.changeset/wise-steaks-end.md

@@ -0,0 +1,9 @@
+---
+"wrangler": patch
+---
+
+feat: `--assets` / `config.assets` to serve a folder of static assets
+
+This adds support for defining `assets` in `wrangler.toml`. You can configure it with a string path, or a `{bucket, include, exclude}` object (much like `[site]`). This also renames the `--experimental-public` arg as `--assets`.
+
+Via https://github.com/cloudflare/wrangler2/issues/1162

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

@@ -412,6 +412,59 @@ describe("normalizeAndValidateConfig()", () => {
       });
     });
 
+    describe("assets", () => {
+      it("should error if `assets` config is missing `bucket`", () => {
+        const expectedConfig: RawConfig = {
+          // @ts-expect-error we're intentionally passing an invalid configuration here
+          assets: {
+            include: ["INCLUDE_1", "INCLUDE_2"],
+            exclude: ["EXCLUDE_1", "EXCLUDE_2"],
+          },
+        };
+
+        const { config, diagnostics } = normalizeAndValidateConfig(
+          expectedConfig,
+          undefined,
+          { env: undefined }
+        );
+
+        expect(config).toEqual(expect.objectContaining(expectedConfig));
+        expect(diagnostics.hasWarnings()).toBe(false);
+        expect(diagnostics.hasErrors()).toBe(true);
+
+        expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+          "Processing wrangler configuration:
+            - \\"assets.bucket\\" is a required field."
+        `);
+      });
+
+      it("should error on invalid `assets` values", () => {
+        const expectedConfig = {
+          assets: {
+            bucket: "BUCKET",
+            include: [222, 333],
+            exclude: [444, 555],
+          },
+        };
+
+        const { config, diagnostics } = normalizeAndValidateConfig(
+          expectedConfig as unknown as RawConfig,
+          undefined,
+          { env: undefined }
+        );
+
+        expect(config).toEqual(expect.objectContaining(expectedConfig));
+        expect(diagnostics.hasWarnings()).toBe(false);
+        expect(diagnostics.renderErrors()).toMatchInlineSnapshot(`
+          "Processing wrangler configuration:
+            - Expected \\"assets.include.[0]\\" to be of type string but got 222.
+            - Expected \\"assets.include.[1]\\" to be of type string but got 333.
+            - Expected \\"assets.exclude.[0]\\" to be of type string but got 444.
+            - Expected \\"assets.exclude.[1]\\" to be of type string but got 555."
+        `);
+      });
+    });
+
     it("should map `wasm_module` paths from relative to the config path to relative to the cwd", () => {
       const expectedConfig: RawConfig = {
         wasm_modules: {

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

@@ -799,7 +799,7 @@ describe("wrangler dev", () => {
     });
   });
 
-  describe("site", () => {
+  describe("serve static assets", () => {
     it("should error if --site is used with no value", async () => {
       await expect(
         runWrangler("dev --site")
@@ -839,7 +839,7 @@ describe("wrangler dev", () => {
               --routes, --route                            Routes to upload  [array]
               --host                                       Host to forward requests to, defaults to the zone of project  [string]
               --local-protocol                             Protocol to listen to requests on, defaults to http.  [choices: \\"http\\", \\"https\\"]
-              --experimental-public                        Static assets to be served  [string]
+              --assets                                     Static assets to be served  [string]
               --site                                       Root folder of static assets for Workers Sites  [string]
               --site-include                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.  [array]
               --site-exclude                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.  [array]
@@ -857,19 +857,19 @@ describe("wrangler dev", () => {
       `);
     });
 
-    it("should error if --experimental-public and --site are used together", async () => {
+    it("should error if --assets and --site are used together", async () => {
       writeWranglerToml({
         main: "./index.js",
       });
       fs.writeFileSync("index.js", `export default {};`);
       await expect(
-        runWrangler("dev --experimental-public abc --site xyz")
+        runWrangler("dev --assets abc --site xyz")
       ).rejects.toThrowErrorMatchingInlineSnapshot(
-        `"Cannot use --experimental-public and a Site configuration together."`
+        `"Cannot use Assets and Workers Sites in the same Worker."`
       );
     });
 
-    it("should error if --experimental-public and config.site are used together", async () => {
+    it("should error if --assets and config.site are used together", async () => {
       writeWranglerToml({
         main: "./index.js",
         site: {
@@ -878,11 +878,56 @@ describe("wrangler dev", () => {
       });
       fs.writeFileSync("index.js", `export default {};`);
       await expect(
-        runWrangler("dev --experimental-public abc")
+        runWrangler("dev --assets abc")
       ).rejects.toThrowErrorMatchingInlineSnapshot(
-        `"Cannot use --experimental-public and a Site configuration together."`
+        `"Cannot use Assets and Workers Sites in the same Worker."`
       );
     });
+
+    it("should error if config.assets and --site are used together", async () => {
+      writeWranglerToml({
+        main: "./index.js",
+        assets: "abc",
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await expect(
+        runWrangler("dev --site xyz")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Cannot use Assets and Workers Sites in the same Worker."`
+      );
+    });
+
+    it("should error if config.assets and config.site are used together", async () => {
+      writeWranglerToml({
+        main: "./index.js",
+        assets: "abc",
+        site: {
+          bucket: "xyz",
+        },
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await expect(
+        runWrangler("dev --assets abc")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Cannot use Assets and Workers Sites in the same Worker."`
+      );
+    });
+
+    it("should indicate whether Sites is being used", async () => {
+      writeWranglerToml({
+        main: "index.js",
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+
+      await runWrangler("dev");
+      expect((Dev as jest.Mock).mock.calls[0][0].isWorkersSite).toEqual(false);
+
+      await runWrangler("dev --site abc");
+      expect((Dev as jest.Mock).mock.calls[1][0].isWorkersSite).toEqual(true);
+
+      await runWrangler("dev --assets abc");
+      expect((Dev as jest.Mock).mock.calls[2][0].isWorkersSite).toEqual(false);
+    });
   });
 
   describe("--inspect", () => {

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

@@ -1404,7 +1404,7 @@ addEventListener('fetch', event => {});`
       expect(std.err).toMatchInlineSnapshot(`""`);
     });
 
-    it("should upload all the files in the directory specified by `--experimental-public`", async () => {
+    it("should upload all the files in the directory specified by `--assets`", async () => {
       const assets = [
         { filePath: "file-1.txt", content: "Content of file-1" },
         { filePath: "file-2.txt", content: "Content of file-2" },
@@ -1425,7 +1425,7 @@ addEventListener('fetch', event => {});`
       mockListKVNamespacesRequest(kvNamespace);
       mockKeyListRequest(kvNamespace.id, []);
       mockUploadAssetsToKVRequest(kvNamespace.id, assets);
-      await runWrangler("publish --experimental-public assets");
+      await runWrangler("publish --assets assets");
 
       expect(std.out).toMatchInlineSnapshot(`
         "Reading file-1.txt...
@@ -1440,19 +1440,31 @@ addEventListener('fetch', event => {});`
       expect(std.err).toMatchInlineSnapshot(`""`);
     });
 
-    it("should error if --experimental-public and --site are used together", async () => {
+    it("should error when trying to use --assets with a service-worker Worker", async () => {
+      writeWranglerToml({
+        main: "./index.js",
+      });
+      writeWorkerSource({ type: "sw" });
+      await expect(
+        runWrangler("publish --assets abc")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"You cannot use the service-worker format with an \`assets\` directory yet. For information on how to migrate to the module-worker format, see https://developers.cloudflare.com/workers/learning/migrating-to-module-workers/"`
+      );
+    });
+
+    it("should error if --assets and --site are used together", async () => {
       writeWranglerToml({
         main: "./index.js",
       });
       writeWorkerSource();
       await expect(
-        runWrangler("publish --experimental-public abc --site xyz")
+        runWrangler("publish --assets abc --site xyz")
       ).rejects.toThrowErrorMatchingInlineSnapshot(
-        `"Cannot use --experimental-public and a Site configuration together."`
+        `"Cannot use Assets and Workers Sites in the same Worker."`
       );
     });
 
-    it("should error if --experimental-public and config.site are used together", async () => {
+    it("should error if --assets and config.site are used together", async () => {
       writeWranglerToml({
         main: "./index.js",
         site: {
@@ -1461,9 +1473,38 @@ addEventListener('fetch', event => {});`
       });
       writeWorkerSource();
       await expect(
-        runWrangler("publish --experimental-public abc")
+        runWrangler("publish --assets abc")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Cannot use Assets and Workers Sites in the same Worker."`
+      );
+    });
+
+    it("should error if config.assets and --site are used together", async () => {
+      writeWranglerToml({
+        main: "./index.js",
+        assets: "abc",
+      });
+      writeWorkerSource();
+      await expect(
+        runWrangler("publish --site xyz")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Cannot use Assets and Workers Sites in the same Worker."`
+      );
+    });
+
+    it("should error if config.assets and config.site are used together", async () => {
+      writeWranglerToml({
+        main: "./index.js",
+        assets: "abc",
+        site: {
+          bucket: "xyz",
+        },
+      });
+      writeWorkerSource();
+      await expect(
+        runWrangler("publish")
       ).rejects.toThrowErrorMatchingInlineSnapshot(
-        `"Cannot use --experimental-public and a Site configuration together."`
+        `"Cannot use Assets and Workers Sites in the same Worker."`
       );
     });
 

packages/wrangler/src/config/config.ts

@@ -114,6 +114,15 @@ export interface ConfigFields<Dev extends RawDevConfig> {
       }
     | undefined;
 
+  /**
+   * Serve a folder of static assets with your Worker, without any additional code.
+   * This can either be a string, or an object with additional config fields.
+   */
+  assets:
+    | string
+    | { bucket: string; include: string[]; exclude: string[] }
+    | undefined;
+
   /**
    * A list of wasm modules that your worker should be bound to. This is
    * the "legacy" way of binding to a wasm module. ES module workers should

packages/wrangler/src/config/validation.ts

@@ -186,6 +186,7 @@ export function normalizeAndValidateConfig(
       rawConfig,
       activeEnv.main
     ),
+    assets: normalizeAndValidateAssets(diagnostics, configPath, rawConfig),
     wasm_modules: normalizeAndValidateModulePaths(
       diagnostics,
       configPath,
@@ -571,6 +572,35 @@ function normalizeAndValidateSite(
   return undefined;
 }
 
+/**
+ * Validate the `assets` configuration and return normalized values.
+ */
+function normalizeAndValidateAssets(
+  diagnostics: Diagnostics,
+  configPath: string | undefined,
+  rawConfig: RawConfig
+) {
+  if (
+    typeof rawConfig?.assets === "string" ||
+    rawConfig?.assets === undefined
+  ) {
+    return rawConfig?.assets;
+  }
+
+  const { bucket, include = [], exclude = [], ...rest } = rawConfig.assets;
+
+  validateAdditionalProperties(diagnostics, "assets", Object.keys(rest), []);
+  validateRequiredProperty(diagnostics, "assets", "bucket", bucket, "string");
+  validateTypedArray(diagnostics, "assets.include", include, "string");
+  validateTypedArray(diagnostics, "assets.exclude", exclude, "string");
+
+  return {
+    bucket,
+    include,
+    exclude,
+  };
+}
+
 /**
  * Map the paths of the `wasm_modules`, `text_blobs` or `data_blobs` configuration to be relative to the current working directory.
  */

packages/wrangler/src/dev/dev.tsx

@@ -38,7 +38,7 @@ export type DevProps = {
   enableLocalPersistence: boolean;
   bindings: CfWorkerInit["bindings"];
   crons: Config["triggers"]["crons"];
-  public: string | undefined;
+  isWorkersSite: boolean;
   assetPaths: AssetPaths | undefined;
   compatibilityDate: string;
   compatibilityFlags: string[] | undefined;
@@ -53,9 +53,13 @@ export type DevProps = {
 };
 
 export function DevImplementation(props: DevProps): JSX.Element {
-  if (props.public && props.entry.format === "service-worker") {
+  if (
+    !props.isWorkersSite &&
+    props.assetPaths &&
+    props.entry.format === "service-worker"
+  ) {
     throw new Error(
-      "You cannot use the service-worker format with a `public` directory."
+      "You cannot use the service-worker format with an `assets` directory yet. For information on how to migrate to the module-worker format, see https://developers.cloudflare.com/workers/learning/migrating-to-module-workers/"
     );
   }
 
@@ -131,12 +135,12 @@ function DevSession(props: DevSessionProps) {
   const bundle = useEsbuild({
     entry: props.entry,
     destination: directory,
-    staticRoot: props.public,
     jsxFactory: props.jsxFactory,
     rules: props.rules,
     jsxFragment: props.jsxFragment,
-    // In dev for remote mode, we serve --experimental-assets from the local proxy before we send the request to the worker.
-    serveAssetsFromWorker: !!props.public && !!props.local,
+    serveAssetsFromWorker: Boolean(
+      props.assetPaths && !props.isWorkersSite && !props.local
+    ),
     tsconfig: props.tsconfig,
     minify: props.minify,
     nodeCompat: props.nodeCompat,
@@ -152,7 +156,7 @@ function DevSession(props: DevSessionProps) {
       compatibilityFlags={props.compatibilityFlags}
       bindings={props.bindings}
       assetPaths={props.assetPaths}
-      public={props.public}
+      isWorkersSite={props.isWorkersSite}
       port={props.port}
       ip={props.ip}
       rules={props.rules}
@@ -168,7 +172,7 @@ function DevSession(props: DevSessionProps) {
       accountId={props.accountId}
       bindings={props.bindings}
       assetPaths={props.assetPaths}
-      public={props.public}
+      isWorkersSite={props.isWorkersSite}
       port={props.port}
       ip={props.ip}
       localProtocol={props.localProtocol}