docs(bundler): clarify that publicPath does not rewrite external module specifiers

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,

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:
 
 <CodeGroup>
 
@@ -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.

docs/snippets/cli/build.mdx

@@ -79,7 +79,7 @@ bun build <entry points>
 </ParamField>
 
 <ParamField path="--public-path" type="string">
-  Prefix to be added to import paths in bundled code
+  Prefix for emitted asset, chunk, and source-map paths
 </ParamField>
 
 <ParamField path="--external" type="string">

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 <STR>              A prefix to be appended to any import paths in bundled code"
+            "--public-path <STR>              A prefix for emitted asset, chunk, and source-map paths"
         ),
         parse_param!(
             "-e, --external <STR>...          Exclude module from transpilation (can use * wildcards). ex: -e react"

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")],