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` (and adds `--assets-include and `--assets-exclude` for parity with Sites.

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` (and adds `--assets-include and `--assets-exclude` for parity with Sites.
+
+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

@@ -839,7 +839,9 @@ 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]
+              --assets-include                             Array of .gitignore-style patterns that match file or directory names from the assets directory. Only matched items will be uploaded.  [array]
+              --assets-exclude                             Array of .gitignore-style patterns that match file or directory names from the assets directory. Matched items will not be uploaded.  [array]
               --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]

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,
@@ -562,6 +563,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

@@ -39,7 +39,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;
@@ -62,9 +62,13 @@ export function DevImplementation(props: DevProps): JSX.Element {
 
   useCustomBuild(props.entry, props.build);
 
-  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."
     );
   }
 
@@ -89,11 +93,13 @@ export function DevImplementation(props: DevProps): JSX.Element {
   const bundle = useEsbuild({
     entry: props.entry,
     destination: directory,
-    staticRoot: props.public,
+    staticRoot: props.isWorkersSite
+      ? undefined
+      : props.assetPaths?.assetDirectory,
     jsxFactory: props.jsxFactory,
     rules: props.rules,
     jsxFragment: props.jsxFragment,
-    serveAssetsFromWorker: !!props.public,
+    serveAssetsFromWorker: Boolean(!props.isWorkersSite && props.assetPaths),
     tsconfig: props.tsconfig,
     minify: props.minify,
     nodeCompat: props.nodeCompat,
@@ -161,7 +167,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}
@@ -177,7 +183,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}

packages/wrangler/src/dev/local.tsx

@@ -22,7 +22,7 @@ interface LocalProps {
   compatibilityFlags: string[] | undefined;
   bindings: CfWorkerInit["bindings"];
   assetPaths: AssetPaths | undefined;
-  public: string | undefined;
+  isWorkersSite: boolean;
   port: number;
   ip: string;
   rules: Config["rules"];
@@ -49,7 +49,7 @@ function useLocalWorker({
   compatibilityFlags,
   bindings,
   assetPaths,
-  public: publicDirectory,
+  isWorkersSite,
   port,
   rules,
   enableLocalPersistence,
@@ -82,9 +82,9 @@ function useLocalWorker({
         abortSignal: abortController.signal,
       });
 
-      if (publicDirectory) {
+      if (!isWorkersSite && assetPaths) {
         throw new Error(
-          '⎔ A "public" folder is not yet supported in local mode.'
+          '⎔ An "assets" folder is not yet supported in local mode.'
         );
       }
       if (bindings.services && bindings.services.length > 0) {
@@ -307,7 +307,7 @@ function useLocalWorker({
     compatibilityFlags,
     localPersistencePath,
     assetPaths,
-    publicDirectory,
+    isWorkersSite,
     rules,
     bindings.wasm_modules,
     bindings.text_blobs,

packages/wrangler/src/dev/remote.tsx

@@ -16,7 +16,7 @@ export function Remote(props: {
   name: string | undefined;
   bundle: EsbuildBundle | undefined;
   format: CfScriptFormat | undefined;
-  public: string | undefined;
+  isWorkersSite: boolean;
   assetPaths: AssetPaths | undefined;
   port: number;
   ip: string;
@@ -40,6 +40,7 @@ export function Remote(props: {
     accountId: props.accountId,
     bindings: props.bindings,
     assetPaths: props.assetPaths,
+    isWorkersSite: props.isWorkersSite,
     port: props.port,
     compatibilityDate: props.compatibilityDate,
     compatibilityFlags: props.compatibilityFlags,
@@ -52,7 +53,9 @@ export function Remote(props: {
 
   usePreviewServer({
     previewToken,
-    publicRoot: props.public,
+    assetDirectory: props.isWorkersSite
+      ? undefined
+      : props.assetPaths?.assetDirectory,
     localProtocol: props.localProtocol,
     localPort: props.port,
     ip: props.ip,
@@ -74,6 +77,7 @@ export function useWorker(props: {
   accountId: string | undefined;
   bindings: CfWorkerInit["bindings"];
   assetPaths: AssetPaths | undefined;
+  isWorkersSite: boolean;
   port: number;
   compatibilityDate: string | undefined;
   compatibilityFlags: string[] | undefined;
@@ -131,7 +135,7 @@ export function useWorker(props: {
         // include it in the kv namespace name regardless (since there's no
         // concept of service environments for kv namespaces yet).
         name + (!props.legacyEnv && props.env ? `-${props.env}` : ""),
-        assetPaths,
+        props.isWorkersSite ? assetPaths : undefined,
         true,
         false
       ); // TODO: cancellable?
@@ -223,6 +227,7 @@ export function useWorker(props: {
     accountId,
     port,
     assetPaths,
+    props.isWorkersSite,
     compatibilityDate,
     compatibilityFlags,
     usageModel,