add install.saveTextLockfile to bunfig.toml (#15827)

Author: dylan-conway

docs/cli/bun-install.md

@@ -47,6 +47,9 @@ registry = "https://registry.yarnpkg.com/"
 # Install for production? This is the equivalent to the "--production" CLI argument
 production = false
 
+# Save a text-based lockfile? This is equivalent to the "--save-text-lockfile" CLI argument
+saveTextLockfile = false
+
 # Disallow changes to lockfile? This is the equivalent to the "--frozen-lockfile" CLI argument
 frozenLockfile = false
 
@@ -108,6 +111,7 @@ export interface Install {
   scopes: Scopes;
   registry: Registry;
   production: boolean;
+  saveTextLockfile: boolean;
   frozenLockfile: boolean;
   dryRun: boolean;
   optional: boolean;

docs/cli/install.md

@@ -174,6 +174,9 @@ peer = true
 # equivalent to `--production` flag
 production = false
 
+# equivalent to `--save-text-lockfile` flag
+saveTextLockfile = false
+
 # equivalent to `--frozen-lockfile` flag
 frozenLockfile = false
 

docs/install/index.md

@@ -86,6 +86,9 @@ peer = true
 # equivalent to `--production` flag
 production = false
 
+# equivalent to `--save-text-lockfile` flag
+saveTextLockfile = false
+
 # equivalent to `--frozen-lockfile` flag
 frozenLockfile = false
 

docs/install/lockfile.md

@@ -72,6 +72,24 @@ $ bun install --yarn
 print = "yarn"
 ```
 
+### Text-based lockfile
+
+Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without configuration, at [no cost to performance](https://bun.sh/blog/bun-lock-text-lockfile#cached-bun-install-gets-30-faster).
+
+To generate the lockfile, use `--save-text-lockfile` with `bun install`. You can do this for new projects and existing projects already using `bun.lockb` (resolutions will be preserved).
+
+```bash
+$ bun install --save-text-lockfile
+$ head -n3 bun.lock
+{
+  "lockfileVersion": 0,
+  "workspaces": {
+```
+
+Once `bun.lock` is generated, Bun will use it for all subsequent installs and updates through commands that read and modify the lockfile. If both lockfiles exist, `bun.lock` will be choosen over `bun.lockb`.
+
+Bun v1.2.0 will switch the default lockfile format to `bun.lock`.
+
 {% /codetabs %}
 
 {% details summary="Configuring lockfile" %}

docs/runtime/bunfig.md

@@ -238,6 +238,17 @@ By default Bun uses caret ranges; if the `latest` version of a package is `2.4.1
 exact = false
 ```
 
+### `install.saveTextLockfile`
+
+Generate `bun.lock`, a human-readable text-based lockfile. Once generated, Bun will use this file instead of `bun.lockb`, choosing it over the binary lockfile if both are present.
+
+Default `false`. In Bun v1.2.0 the default lockfile format will change to `bun.lock`.
+
+```toml
+[install]
+saveTextLockfile = true
+```
+
 <!--
 ### `install.prefer`
 

src/api/schema.zig

@@ -2979,6 +2979,8 @@ pub const Api = struct {
 
         cafile: ?[]const u8 = null,
 
+        save_text_lockfile: ?bool = null,
+
         ca: ?union(enum) {
             str: []const u8,
             list: []const []const u8,

src/bunfig.zig

@@ -469,6 +469,12 @@ pub const Bunfig = struct {
                         }
                     }
 
+                    if (install_obj.get("saveTextLockfile")) |save_text_lockfile| {
+                        if (save_text_lockfile.asBool()) |value| {
+                            install.save_text_lockfile = value;
+                        }
+                    }
+
                     if (install_obj.get("concurrentScripts")) |jobs| {
                         if (jobs.data == .e_number) {
                             install.concurrent_scripts = jobs.data.e_number.toU32();

src/install/install.zig

@@ -7237,6 +7237,10 @@ pub const PackageManager = struct {
                     }
                 }
 
+                if (config.save_text_lockfile) |save_text_lockfile| {
+                    this.save_text_lockfile = save_text_lockfile;
+                }
+
                 if (config.concurrent_scripts) |jobs| {
                     this.max_concurrent_lifecycle_scripts = jobs;
                 }
@@ -7395,7 +7399,9 @@ pub const PackageManager = struct {
                     this.do.trust_dependencies_from_args = true;
                 }
 
-                this.save_text_lockfile = cli.save_text_lockfile;
+                if (cli.save_text_lockfile) |save_text_lockfile| {
+                    this.save_text_lockfile = save_text_lockfile;
+                }
 
                 this.local_package_features.optional_dependencies = !cli.omit.optional;
 
@@ -9498,7 +9504,7 @@ pub const PackageManager = struct {
         ca: []const string = &.{},
         ca_file_name: string = "",
 
-        save_text_lockfile: bool = false,
+        save_text_lockfile: ?bool = null,
 
         const PatchOpts = union(enum) {
             nothing: struct {},

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

@@ -54,3 +54,20 @@ note: Package name is also declared here
    at [dir]/bar/package.json:1:9
 "
 `;
+
+exports[`should read install.saveTextLockfile from bunfig.toml 1`] = `
+"{
+  "lockfileVersion": 0,
+  "workspaces": {
+    "": {},
+    "packages/pkg1": {
+      "name": "pkg-one",
+      "version": "1.0.0",
+    },
+  },
+  "packages": {
+    "pkg-one": ["pkg-one@workspace:packages/pkg1", {}],
+  }
+}
+"
+`;

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

@@ -1,4 +1,4 @@
-import { file, listen, Socket, spawn } from "bun";
+import { file, listen, Socket, spawn, write } from "bun";
 import {
   afterAll,
   afterEach,
@@ -11,7 +11,7 @@ import {
   setDefaultTimeout,
   test,
 } from "bun:test";
-import { access, mkdir, readlink, rm, writeFile, cp, stat } from "fs/promises";
+import { access, mkdir, readlink, rm, writeFile, cp, stat, exists } from "fs/promises";
 import {
   bunEnv,
   bunExe,
@@ -35,6 +35,7 @@ import {
   requested,
   root_url,
   setHandler,
+  getPort,
 } from "./dummy.registry.js";
 
 expect.extend({
@@ -8361,3 +8362,53 @@ cache = false
   expect(await new Response(stdout).text()).toContain("installed @~39/[email protected]");
   expect(await exited).toBe(0);
 });
+
+it("should read install.saveTextLockfile from bunfig.toml", async () => {
+  await Promise.all([
+    write(
+      join(package_dir, "bunfig.toml"),
+      `
+[install]
+cache = false
+registry = "http://localhost:${getPort()}/"
+saveTextLockfile = true
+`,
+    ),
+    write(
+      join(package_dir, "package.json"),
+      JSON.stringify({
+        name: "foo",
+        workspaces: ["packages/*"],
+      }),
+    ),
+    write(
+      join(package_dir, "packages", "pkg1", "package.json"),
+      JSON.stringify({
+        name: "pkg-one",
+        version: "1.0.0",
+      }),
+    ),
+  ]);
+
+  const { stdout, stderr, exited } = spawn({
+    cmd: [bunExe(), "install"],
+    cwd: package_dir,
+    stdout: "pipe",
+    stderr: "pipe",
+    env,
+  });
+
+  const err = await Bun.readableStreamToText(stderr);
+  expect(err).not.toContain("error:");
+  expect(err).toContain("Saved lockfile");
+  const out = await Bun.readableStreamToText(stdout);
+  expect(out).toContain("1 package installed");
+
+  expect(await exited).toBe(0);
+  expect(await Bun.file(join(package_dir, "node_modules", "pkg-one", "package.json")).json()).toEqual({
+    name: "pkg-one",
+    version: "1.0.0",
+  });
+  expect(await exists(join(package_dir, "bun.lockb"))).toBeFalse();
+  expect(await file(join(package_dir, "bun.lock")).text()).toMatchSnapshot();
+});

test/cli/install/dummy.registry.ts

@@ -116,6 +116,10 @@ export function dummyAfterAll() {
   server.stop();
 }
 
+export function getPort() {
+  return server.port;
+}
+
 let packageDirGetter: () => string = () => {
   return tmpdirSync();
 };