install: document that --production implies --frozen-lockfile

docs/pm/cli/install.mdx

@@ -158,13 +158,15 @@ cowsay "Bun!"
 
 ## Production mode
 
-To install in production mode (without `devDependencies` or `optionalDependencies`):
+To install in production mode (without `devDependencies`):
 
 ```bash terminal icon="terminal"
 bun install --production
 ```
 
-For reproducible installs, use `--frozen-lockfile`. Bun installs the exact versions specified in the lockfile and does not update it. If your `package.json` disagrees with `bun.lock`, Bun exits with an error.
+Passing `--production` also implies `--frozen-lockfile`, so the install fails if `package.json` is out of sync with the lockfile. If you only want to skip `devDependencies` without freezing the lockfile, use `--omit=dev` instead.
+
+For reproducible installs without skipping `devDependencies`, use `--frozen-lockfile` on its own. Bun installs the exact versions specified in the lockfile and does not update it. If your `package.json` disagrees with `bun.lock`, Bun exits with an error.
 
 ```bash terminal icon="terminal"
 bun install --frozen-lockfile

docs/runtime/bunfig.mdx

@@ -430,7 +430,7 @@ peer = true
 
 Whether `bun install` runs in "production mode". Default `false`.
 
-In production mode, `"devDependencies"` are not installed. The `--production` CLI flag overrides this setting.
+In production mode, `"devDependencies"` are not installed and the lockfile is frozen (as if `--frozen-lockfile` was passed), so installs fail if `package.json` disagrees with `bun.lock`. The `--production` CLI flag overrides this setting.
 
 ```toml title="bunfig.toml" icon="settings"
 [install]

docs/snippets/cli/install.mdx

@@ -16,9 +16,9 @@
 
 ### Dependency Scope & Management
 
 <ParamField path="--production" type="boolean">
-  Don't install devDependencies
+  Don't install devDependencies. Implies --frozen-lockfile
 </ParamField>
 
 <ParamField path="--no-save" type="boolean">
   Don't update package.json or save a lockfile

src/install/PackageManager/CommandLineArguments.rs

@@ -56,7 +56,9 @@ const BACKEND_PARAM: ParamType = clap::param!(
 const SHARED_PARAMS: &[ParamType] = &[
     clap::param!("-c, --config <STR>?                   Specify path to config file (bunfig.toml)"),
     clap::param!("-y, --yarn                            Write a yarn.lock file (yarn v1)"),
-    clap::param!("-p, --production                      Don't install devDependencies"),
+    clap::param!(
+        "-p, --production                      Don't install devDependencies. Implies --frozen-lockfile"
+    ),
     clap::param!("-P, --prod"),
     clap::param!(
         "--no-save                             Don't update package.json or save a lockfile"

src/install/PackageManager/install_with_manager.rs

@@ -735,9 +735,9 @@
                 bun_core::pretty_errorln!(
                     "<r><red>error<r><d>:<r> lockfile had changes, but lockfile is frozen"
                 );
                 bun_core::note!(
-                    "try re-running without <d>--frozen-lockfile<r> and commit the updated lockfile"
+                    "try re-running without <d>--frozen-lockfile<r> or <d>--production<r> and commit the updated lockfile"
                 );
             }
             Global::crash();
         }

test/cli/install/bun-install.test.ts

@@ -6764,6 +6764,68 @@
     });
   });
 
+  // https://github.com/oven-sh/bun/issues/10949
+  it("documents that --production implies --frozen-lockfile", async () => {
+    await withContext(defaultOpts, async ctx => {
+      let urls: string[] = [];
+      setContextHandler(
+        ctx,
+        dummyRegistryForContext(ctx, urls, { "0.0.3": { as: "0.0.3" }, "0.0.5": { as: "0.0.5" } }),
+      );
+
+      // --help should say that --production implies --frozen-lockfile
+      const help = spawn({
+        cmd: [bunExe(), "install", "--help"],
+        cwd: ctx.package_dir,
+        stdout: "pipe",
+        stderr: "pipe",
+        env,
+      });
+      const [helpOut, helpErr] = await Promise.all([help.stdout.text(), help.stderr.text()]);
+      const helpText = helpOut + helpErr;
+      const productionLine = helpText.split("\n").find(line => line.includes("--production"));
+      expect(productionLine).toMatch(/--production.*Implies --frozen-lockfile/);
+      expect(await help.exited).toBe(0);
+
+      await writeFile(
+        join(ctx.package_dir, "package.json"),
+        JSON.stringify({ name: "foo", version: "0.0.1", dependencies: { baz: "0.0.3" } }),
+      );
+
+      expect(
+        await spawn({
+          cmd: [bunExe(), "install"],
+          cwd: ctx.package_dir,
+          stdout: "ignore",
+          stdin: "ignore",
+          stderr: "ignore",
+          env,
+        }).exited,
+      ).toBe(0);
+
+      // change version of baz in package.json so it disagrees with the lockfile
+      await writeFile(
+        join(ctx.package_dir, "package.json"),
+        JSON.stringify({ name: "foo", version: "0.0.1", dependencies: { baz: "0.0.5" } }),
+      );
+
+      const { stderr, exited } = spawn({
+        cmd: [bunExe(), "install", "--production"],
+        cwd: ctx.package_dir,
+        stdout: "pipe",
+        stdin: "pipe",
+        stderr: "pipe",
+        env,
+      });
+
+      // the note should mention --production, not just --frozen-lockfile
+      const err = await stderr.text();
+      expect(err).toContain("error: lockfile had changes, but lockfile is frozen");
+      expect(err).toContain("--production");
+      expect(await exited).toBe(1);
+    });
+  });
+
   it("should perform bin-linking across multiple dependencies", async () => {
     await withContext(defaultOpts, async ctx => {
       const foo_package = JSON.stringify({