From b0c5a7655dac9040655a22754c5eab91046e923b Mon Sep 17 00:00:00 2001 From: pfg Date: Tue, 21 Jan 2025 22:09:23 -0800 Subject: [PATCH] Update docs for bun.lock (#16585) --- bench/install/README.md | 2 +- docs/cli/bun-install.md | 24 ++--- docs/cli/install.md | 6 +- docs/guides/ecosystem/docker.md | 4 +- docs/guides/ecosystem/render.md | 2 +- .../from-npm-install-to-bun-install.md | 2 +- docs/guides/install/trusted.md | 2 +- docs/guides/install/yarnlock.md | 10 +-- docs/install/index.md | 2 +- docs/install/lockfile.md | 88 ++----------------- docs/install/workspaces.md | 2 +- docs/nav.ts | 2 +- docs/runtime/autoimport.md | 2 +- docs/runtime/bunfig.md | 10 +-- packages/bun-vscode/README.md | 2 +- 15 files changed, 36 insertions(+), 124 deletions(-) diff --git a/bench/install/README.md b/bench/install/README.md index 42739a1aa4c478..e94ce6697667f4 100644 --- a/bench/install/README.md +++ b/bench/install/README.md @@ -23,7 +23,7 @@ $ hyperfine --prepare 'rm -rf node_modules' --runs 1 'bun install' 'pnpm install To run the benchmark with offline mode but without lockfiles: ```sh -$ hyperfine --prepare 'rm -rf node_modules' --warmup 1 'rm bun.lockb && bun install' 'rm pnpm-lock.yaml && pnpm install --prefer-offline' 'rm yarn.lock && yarn --offline' 'rm package-lock.json && npm install --prefer-offline' +$ hyperfine --prepare 'rm -rf node_modules' --warmup 1 'rm bun.lock && bun install' 'rm pnpm-lock.yaml && pnpm install --prefer-offline' 'rm yarn.lock && yarn --offline' 'rm package-lock.json && npm install --prefer-offline' ``` ## diff --git a/docs/cli/bun-install.md b/docs/cli/bun-install.md index a2eb2ee19610ff..833c3f163ae5d9 100644 --- a/docs/cli/bun-install.md +++ b/docs/cli/bun-install.md @@ -95,7 +95,7 @@ disableManifest = false [install.lockfile] # Print a yarn v1 lockfile -# Note: it does not load the lockfile, it just converts bun.lockb into a yarn.lock +# Note: it does not load the lockfile, it just converts bun.lock into a yarn.lock print = "yarn" # Save the lockfile to disk @@ -170,9 +170,9 @@ Bun stores installed packages from npm in `~/.bun/install/cache/${name}@${versio When the `node_modules` folder exists, before installing, Bun checks if the `"name"` and `"version"` in `package/package.json` in the expected node_modules folder matches the expected `name` and `version`. This is how it determines whether it should install. It uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`. -When a `bun.lockb` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving. +When a `bun.lock` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving. -When a `bun.lockb` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball. +When a `bun.lock` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball. ## Platform-specific dependencies? @@ -184,23 +184,9 @@ Peer dependencies are handled similarly to yarn. `bun install` will automaticall ## Lockfile -`bun.lockb` is Bun’s binary lockfile format. +`bun.lock` is Bun’s lockfile format. See [our blogpost about the text lockfile](https://bun.sh/blog/bun-lock-text-lockfile). -## Why is it binary? - -In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles. - -## How do I inspect it? - -For now, the easiest thing is to run `bun install -y`. That prints a Yarn v1-style yarn.lock file. - -## What does the lockfile store? - -Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to and which version (or equivalent). - -## Why is it fast? - -It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order. +Prior to Bun 1.2, the lockfile was binary and called `bun.lockb`. Old lockfiles can be upgraded to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only`, and then deleting `bun.lockb`. ## Cache diff --git a/docs/cli/install.md b/docs/cli/install.md index 080b6e0f288564..4ab91d15051192 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -33,7 +33,7 @@ Running `bun install` will: - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default. - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies. -- **Write** a `bun.lockb` lockfile to the project root. +- **Write** a `bun.lock` lockfile to the project root. ## Logging @@ -136,13 +136,13 @@ To install in production mode (i.e. without `devDependencies` or `optionalDepend $ bun install --production ``` -For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated. +For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lock`, Bun will exit with an error. The lockfile will not be updated. ```bash $ bun install --frozen-lockfile ``` -For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile). +For more information on Bun's lockfile `bun.lock`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile). ## Omitting dependencies diff --git a/docs/guides/ecosystem/docker.md b/docs/guides/ecosystem/docker.md index bd9647e1588675..ad8f8907ea4580 100644 --- a/docs/guides/ecosystem/docker.md +++ b/docs/guides/ecosystem/docker.md @@ -22,12 +22,12 @@ WORKDIR /usr/src/app # this will cache them and speed up future builds FROM base AS install RUN mkdir -p /temp/dev -COPY package.json bun.lockb /temp/dev/ +COPY package.json bun.lock /temp/dev/ RUN cd /temp/dev && bun install --frozen-lockfile # install with --production (exclude devDependencies) RUN mkdir -p /temp/prod -COPY package.json bun.lockb /temp/prod/ +COPY package.json bun.lock /temp/prod/ RUN cd /temp/prod && bun install --frozen-lockfile --production # copy node_modules from temp directory diff --git a/docs/guides/ecosystem/render.md b/docs/guides/ecosystem/render.md index 4fa4a887b7ca6f..71b0597ca178db 100644 --- a/docs/guides/ecosystem/render.md +++ b/docs/guides/ecosystem/render.md @@ -53,7 +53,7 @@ app.listen(port, () => { Commit your changes and push to GitHub. ```sh -$ git add app.ts bun.lockb package.json +$ git add app.ts bun.lock package.json $ git commit -m "Create simple Express app" $ git push origin main ``` diff --git a/docs/guides/install/from-npm-install-to-bun-install.md b/docs/guides/install/from-npm-install-to-bun-install.md index 2ab8a8ba1efa21..c8aebecdb7e15a 100644 --- a/docs/guides/install/from-npm-install-to-bun-install.md +++ b/docs/guides/install/from-npm-install-to-bun-install.md @@ -7,7 +7,7 @@ name: Migrate from npm install to bun install We've put a lot of work into making sure that the migration path from `npm install` to `bun install` is as easy as running `bun install` instead of `npm install`. - **Designed for Node.js & Bun**: `bun install` installs a Node.js compatible `node_modules` folder. You can use it in place of `npm install` for Node.js projects without any code changes and without using Bun's runtime. -- **Automatically converts `package-lock.json`** to bun's `bun.lockb` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing. +- **Automatically converts `package-lock.json`** to bun's `bun.lock` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing. - **`.npmrc` compatible**: bun install reads npm registry configuration from npm's `.npmrc`, so you can use the same configuration for both npm and Bun. - **Hardlinks**: On Windows and Linux, `bun install` uses hardlinks to conserve disk space and install times. diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md index 8e51c57f365857..0d598e46625790 100644 --- a/docs/guides/install/trusted.md +++ b/docs/guides/install/trusted.md @@ -37,7 +37,7 @@ Once this is added, run a fresh install. Bun will re-install your dependencies a ```sh $ rm -rf node_modules -$ rm bun.lockb +$ rm bun.lock $ bun install ``` diff --git a/docs/guides/install/yarnlock.md b/docs/guides/install/yarnlock.md index d5383de64bfe0c..8242e3e994cf94 100644 --- a/docs/guides/install/yarnlock.md +++ b/docs/guides/install/yarnlock.md @@ -1,5 +1,5 @@ --- -name: Generate a human-readable lockfile +name: Generate a yarn-compatible lockfile --- {% callout %} @@ -8,11 +8,7 @@ Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is hum --- -By default Bun generates a binary `bun.lockb` file when you run `bun install`. In some cases, it's preferable to generate a human-readable lockfile instead. - ---- - -Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lockb`). +Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lock`). ```sh $ bun install --yarn @@ -29,7 +25,7 @@ print = "yarn" --- -To print a Yarn lockfile to your console without writing it to disk, just "run" your `bun.lockb` with `bun`. +To print a Yarn lockfile to your console without writing it to disk, "run" your `bun.lockb` with `bun`. ```sh $ bun bun.lockb diff --git a/docs/install/index.md b/docs/install/index.md index 0f04c92a126b80..f7bc5a3e21bd3b 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -41,7 +41,7 @@ Running `bun install` will: - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default. - **Run** your project's `{pre|post}install` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies. -- **Write** a `bun.lockb` lockfile to the project root. +- **Write** a `bun.lock` lockfile to the project root. To install in production mode (i.e. without `devDependencies`): diff --git a/docs/install/lockfile.md b/docs/install/lockfile.md index 533bc6489ca32f..b79a10dc14b590 100644 --- a/docs/install/lockfile.md +++ b/docs/install/lockfile.md @@ -1,53 +1,10 @@ -Running `bun install` will create a binary lockfile called `bun.lockb`. +Running `bun install` will create a lockfile called `bun.lock`. -#### Why is it binary? +https://bun.sh/blog/bun-lock-text-lockfile -In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles. +#### Should it be committed to git? -#### How do I inspect Bun's lockfile? - -Run `bun install -y` to generate a Yarn-compatible `yarn.lock` (v1) that can be inspected more easily. - -#### How do I `git diff` Bun's lockfile? - -Add the following to your local or global `.gitattributes` file: - -``` -*.lockb binary diff=lockb -``` - -Then add the following to your local git config with: - -```sh -$ git config diff.lockb.textconv bun -$ git config diff.lockb.binary true -``` - -Or to your global git config (system-wide) with the `--global` option: - -```sh -$ git config --global diff.lockb.textconv bun -$ git config --global diff.lockb.binary true -``` - -**Why this works:** - -- `textconv` tells git to run `bun` on the file before diffing -- `binary` tells git to treat the file as binary (so it doesn't try to diff it line-by-line) - -Running `bun` on a lockfile will print a human-readable diff. So we just need to tell `git` to run `bun` on the lockfile before diffing it. - -#### Platform-specific dependencies? - -Bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won’t change between platforms/architectures even if the packages ultimately installed do change. - -#### What does Bun's lockfile store? - -Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to, and which version (or equivalent). - -#### Why is Bun's lockfile fast? - -It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order. +Yes #### Generate a lockfile without installing? @@ -69,7 +26,7 @@ To install without creating a lockfile: $ bun install --no-save ``` -To install a Yarn lockfile _in addition_ to `bun.lockb`. +To install a Yarn lockfile _in addition_ to `bun.lock`. {% codetabs %} @@ -79,42 +36,15 @@ $ bun install --yarn ```toml#bunfig.toml [install.lockfile] -# whether to save a non-Bun lockfile alongside bun.lockb +# whether to save a non-Bun lockfile alongside bun.lock # only "yarn" is supported print = "yarn" ``` {% /codetabs %} -### 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 chosen over `bun.lockb`. +#### Text-based lockfile -Bun v1.2.0 will switch the default lockfile format to `bun.lock`. - -{% details summary="Configuring lockfile" %} - -```toml -[install.lockfile] - -# whether to save the lockfile to disk -save = true - -# whether to save a non-Bun lockfile alongside bun.lockb -# only "yarn" is supported -print = "yarn" -``` +Bun v1.2 changed the default lockfile format to the text-based `bun.lock`. Existing binary `bun.lockb` lockfiles can be migrated to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only` and deleting `bun.lockb`. -{% /details %} +More information about the new lockfile format can be found on [our blogpost](https://bun.sh/blog/bun-lock-text-lockfile). diff --git a/docs/install/workspaces.md b/docs/install/workspaces.md index fb25a0a7db57e5..d3320f6f760cb5 100644 --- a/docs/install/workspaces.md +++ b/docs/install/workspaces.md @@ -6,7 +6,7 @@ It's common for a monorepo to have the following structure: tree ├── README.md -├── bun.lockb +├── bun.lock ├── package.json ├── tsconfig.json └── packages diff --git a/docs/nav.ts b/docs/nav.ts index 8568243972d9c1..615c1ce7df4af7 100644 --- a/docs/nav.ts +++ b/docs/nav.ts @@ -191,7 +191,7 @@ export default { }), page("install/lockfile", "Lockfile", { description: - "Bun's binary lockfile `bun.lockb` tracks your resolved dependency tree, making future installs fast and repeatable.", + "Bun's lockfile `bun.lock` tracks your resolved dependency tree, making future installs fast and repeatable.", }), page("install/registries", "Scopes and registries", { description: "How to configure private scopes and custom package registries.", diff --git a/docs/runtime/autoimport.md b/docs/runtime/autoimport.md index 1d80440530169f..bca3bca195d303 100644 --- a/docs/runtime/autoimport.md +++ b/docs/runtime/autoimport.md @@ -14,7 +14,7 @@ The first time you run this script, Bun will auto-install `"foo"` and cache it. To determine which version to install, Bun follows the following algorithm: -1. Check for a `bun.lockb` file in the project root. If it exists, use the version specified in the lockfile. +1. Check for a `bun.lock` file in the project root. If it exists, use the version specified in the lockfile. 2. Otherwise, scan up the tree for a `package.json` that includes `"foo"` as a dependency. If found, use the specified semver version or version range. 3. Otherwise, use `latest`. diff --git a/docs/runtime/bunfig.md b/docs/runtime/bunfig.md index 8a19be1ce510f5..36dfa750439307 100644 --- a/docs/runtime/bunfig.md +++ b/docs/runtime/bunfig.md @@ -240,13 +240,13 @@ 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. +If false, generate a binary `bun.lockb` instead of a text-based `bun.lock` file when running `bun install` and no lockfile is present. -Default `false`. In Bun v1.2.0 the default lockfile format will change to `bun.lock`. +Default `true` (since Bun v1.2). ```toml [install] -saveTextLockfile = true +saveTextLockfile = false ```