diff --git a/completions/bun-cli.json b/completions/bun-cli.json index 6dfdac75a8f2..480fee65b69e 100644 --- a/completions/bun-cli.json +++ b/completions/bun-cli.json @@ -3337,7 +3337,7 @@ }, { "name": "public-path", - "description": "A prefix to be appended to any import paths in bundled code", + "description": "A prefix for emitted asset, chunk, and source-map paths", "hasValue": true, "valueType": "val", "required": false, diff --git a/docs/bundler/index.mdx b/docs/bundler/index.mdx index dcca3906df1e..68275f9c3b47 100644 --- a/docs/bundler/index.mdx +++ b/docs/bundler/index.mdx @@ -1050,15 +1050,15 @@ With `.` as `root`, the generated file structure looks like this: ### publicPath -A prefix added to any import paths in bundled code. +A prefix added to the file paths the bundler emits into your code. -In many cases, generated bundles contain no import statements; the goal of bundling is to combine all of the code into a single file. In a few cases, though, the generated bundles contain import statements: +In many cases, generated bundles contain no references to other files; the goal of bundling is to combine all of the code into a single file. In a few cases, though, the bundler writes paths to other output files into the bundle: -- **Asset imports** — When importing an unrecognized file type like `*.svg`, the bundler defers to the file loader, which copies the file into `outdir` as is. The import is converted into a variable. -- **External modules** — Files and modules marked as external are not included in the bundle. Instead, the import statement is left in the final bundle. -- **Chunking.** When `splitting` is enabled, the bundler may generate separate "chunk" files that represent code that is shared among multiple entrypoints. +- **Asset imports** — When importing an unrecognized file type like `*.svg`, the bundler defers to the file loader, which copies the file into `outdir` as is. The import is converted into a variable holding the file's path. +- **Chunking** — When `splitting` is enabled, the bundler may generate separate "chunk" files that represent code shared among multiple entrypoints, and emits `import` statements that reference those chunks. +- **Linked source maps** — With `sourcemap: "linked"`, the bundler emits a `//# sourceMappingURL=` comment pointing at the generated `.map` file. -In any of these cases, the final bundles may contain paths to other files. By default these imports are relative. Here is an example of an asset import: +By default these paths are relative. Here is an example of an asset import: @@ -1099,6 +1099,8 @@ The output file would now look something like this. var logo = "https://cdn.example.com/logo-a7305bdef.svg"; ``` +`publicPath` does not rewrite specifiers for [external](#external) modules. An import marked as external is emitted unchanged so it can be resolved at runtime. + ### define A map of global identifiers to be replaced at build time. Keys of this object are identifier names, and values are JSON strings that are inlined. diff --git a/docs/snippets/cli/build.mdx b/docs/snippets/cli/build.mdx index 56a0d68afcc8..14001e10d2b8 100644 --- a/docs/snippets/cli/build.mdx +++ b/docs/snippets/cli/build.mdx @@ -79,7 +79,7 @@ bun build - Prefix to be added to import paths in bundled code + Prefix for emitted asset, chunk, and source-map paths diff --git a/src/runtime/cli/Arguments.rs b/src/runtime/cli/Arguments.rs index 65d20886727c..811aa540f3a1 100644 --- a/src/runtime/cli/Arguments.rs +++ b/src/runtime/cli/Arguments.rs @@ -471,7 +471,7 @@ pub(crate) const BUILD_ONLY_PARAMS: &[ParamType] = concat_params!( ), parse_param!("--splitting Enable code splitting"), parse_param!( - "--public-path A prefix to be appended to any import paths in bundled code" + "--public-path A prefix for emitted asset, chunk, and source-map paths" ), parse_param!( "-e, --external ... Exclude module from transpilation (can use * wildcards). ex: -e react" diff --git a/test/bundler/cli.test.ts b/test/bundler/cli.test.ts index e47d0ae11df2..288c50542010 100644 --- a/test/bundler/cli.test.ts +++ b/test/bundler/cli.test.ts @@ -6,6 +6,23 @@ import path, { join } from "node:path"; describe.concurrent( "bun build", () => { + // https://github.com/oven-sh/bun/issues/11652 + test("--help describes --public-path by what it prefixes", async () => { + await using proc = Bun.spawn({ + cmd: [bunExe(), "build", "--help"], + env: bunEnv, + stdout: "pipe", + stderr: "pipe", + }); + const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]); + const help = stdout + stderr; + const line = help.split("\n").find(l => l.includes("--public-path")) ?? ""; + expect(line).toMatch(/asset/i); + expect(line).toMatch(/chunk/i); + expect(line).toMatch(/source[- ]?map/i); + expect(exitCode).toBe(0); + }); + test("warnings dont return exit code 1", async () => { const { stderr, exited } = Bun.spawn({ cmd: [bunExe(), "build", path.join(import.meta.dir, "./fixtures/jsx-warning/index.jsx")],