diff options
Diffstat (limited to 'docs/cli')
| -rw-r--r-- | docs/cli/bunx.md | 73 | ||||
| -rw-r--r-- | docs/cli/create.md | 4 | ||||
| -rw-r--r-- | docs/cli/install.md | 111 | ||||
| -rw-r--r-- | docs/cli/run.md | 78 | ||||
| -rw-r--r-- | docs/cli/test.md | 26 |
5 files changed, 202 insertions, 90 deletions
diff --git a/docs/cli/bunx.md b/docs/cli/bunx.md new file mode 100644 index 000000000..e8374cab1 --- /dev/null +++ b/docs/cli/bunx.md @@ -0,0 +1,73 @@ +Use `bunx` to auto-install and run packages from `npm`. The `bunx` CLI will be auto-installed when you install `bun`. + +```bash +$ bunx cowsay "Hello world!" +``` + +{% callout %} +⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages. +{% /callout %} + +Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_. + +```jsonc#package.json +{ + // ... other fields + "name": "my-cli", + "bin": { + "my-cli": "dist/index.js" + } +} +``` + +These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`. + +```js#dist/index.js +#!/usr/bin/env node + +console.log("Hello world!"); +``` + +These executables can be run with `bunx`, + +```bash +$ bunx my-cli +``` + +As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use. + +### Arguments and flags + +To pass additional command-line flags and arguments through to the executable, place them after the executable name. + +```bash +$ bunx my-cli --foo bar +``` + +### Shebangs + +By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag. + +```bash +$ bunx --bun my-cli +``` + +{% callout %} +**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable. + +```bash +$ bunx --bun my-cli # good +$ bunx my-cli --bun # bad +``` + +{% /callout %} + +## Environment variables + +Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order: + +1. `.env.local` (first) +2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development` +3. `.env` + +To debug environment variables, run `bun run env` to view a list of resolved environment variables. diff --git a/docs/cli/create.md b/docs/cli/create.md index 8542db68b..54595a6fe 100644 --- a/docs/cli/create.md +++ b/docs/cli/create.md @@ -188,9 +188,7 @@ When cloning a template, `bun create` will automatically remove the `"bun-create {% /table %} -### How `bun create` works - -{% details summary="View details" %} +{% details summary="How `bun create` works" %} When you run `bun create ${template} ${destination}`, here’s what happens: diff --git a/docs/cli/install.md b/docs/cli/install.md index 777ed2da1..09edc59ec 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -1,6 +1,4 @@ -The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. - -It can be be used as a drop-in replacement for these tools, _regardless of whether you're using Bun's runtime_. +The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project. {% callout %} @@ -86,7 +84,7 @@ dryRun = false {% /details %} -## Adding packages +## Add and remove packages To add or remove a particular package: @@ -149,6 +147,27 @@ To view a complete list of options for a given command: $ bun add --help ``` +## Git dependencies + +To add a dependency from a git repository: + +```bash +$ bun install git@github.com:moment/moment.git +``` + +Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more. + +```json +{ + "dependencies": { + "dayjs": "git+https://github.com/iamkun/dayjs.git", + "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21", + "moment": "git@github.com:moment/moment.git", + "zod": "github:colinhacks/zod" + } +} +``` + ## Global cache All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached. @@ -328,7 +347,7 @@ registry = { url = "https://registry.npmjs.org", token = "123456" } registry = "https://username:password@registry.npmjs.org" ``` -To configure organization-scoped registries: +To configure a private registry scoped to a particular organization: ```toml [install.scopes] @@ -342,3 +361,85 @@ To configure organization-scoped registries: # registry with token "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" } ``` + +## Linking and unlinking + +Use `bun link` in a local directory to register the current package as a "linkable" package. + +```bash +$ cd /path/to/cool-pkg +$ cat package.json +{ + "name": "cool-pkg", + "version": "1.0.0" +} +$ bun link +bun link v0.5.7 (7416672e) +Success! Registered "cool-pkg" + +To use cool-pkg in a project, run: + bun link cool-pkg + +Or add it in dependencies in your package.json file: + "cool-pkg": "link:cool-pkg" +``` + +This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory. + +```bash +$ cd /path/to/my-app +$ bun link cool-pkg +``` + +This will add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`. + +```json-diff + { + "name": "my-app", + "version": "1.0.0", + "dependencies": { ++ "cool-pkg": "link:cool-pkg" + } + } +``` + +## Utilities + +The `bun pm` command group provides a set of utilities for working with Bun's package manager. + +To print the path to the `bin` directory for the local project: + +```bash +$ bun pm bin +/path/to/current/project/node_modules/.bin +``` + +To get the path to the global `bin` directory: + +```bash +$ bun pm bin +<$HOME>/.bun/bin +``` + +To print a list of packages installed in the current project and their resolved versions, excluding their dependencies. Use the `--all` flag to print the entire tree, including all nth-order dependencies. + +```bash +/path/to/project node_modules (5) +├── eslint@8.33.0 +├── react@18.2.0 +├── react-dom@18.2.0 +├── typescript@4.8.4 +└── zod@3.20.1 +``` + +To print the path to Bun's global module cache: + +```bash +$ bun pm cache +``` + +To clear Bun's global module cache: + +```bash +$ bun pm cache rm +``` diff --git a/docs/cli/run.md b/docs/cli/run.md index f180868d2..133f3e1ec 100644 --- a/docs/cli/run.md +++ b/docs/cli/run.md @@ -1,6 +1,6 @@ The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin). -## Run a file +## Running a file {% callout %} Compare to `node <file>` @@ -25,7 +25,7 @@ Billie Eilish If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules). -## Run a package script +## Running a package script {% note %} Compare to `npm run <script>` or `yarn <script>` @@ -80,77 +80,3 @@ quickstart scripts: ``` Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself. - -## Run an executable - -{% callout %} -Compare to `npx <command>` -{% /callout %} - -Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_. - -```jsonc#package.json -{ - // ... other fields - "name": "my-cli", - "bin": { - "my-cli": "dist/index.js" - } -} -``` - -These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`. - -```js#dist/index.js -#!/usr/bin/env node - -console.log("Hello world!"); -``` - -These executables can be run with `bunx`, Bun's equivalent of `npx`. - -{% callout %} -⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages. -{% /callout %} - -```bash -$ bunx my-cli -``` - -As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use. - -### Arguments and flags - -To pass additional command-line flags and arguments through to the executable: - -```bash -$ bunx my-cli --foo bar -``` - -### Shebangs - -By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag. - -```bash -$ bunx --bun my-cli -``` - -{% callout %} -**Note** — The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable. - -```bash -$ bunx --bun my-cli # good -$ bunx my-cli --bun # bad -``` - -{% /callout %} - -## Environment variables - -Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order: - -1. `.env.local` (first) -2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development` -3. `.env` - -To debug environment variables, run `bun run env` to view a list of resolved environment variables. diff --git a/docs/cli/test.md b/docs/cli/test.md index 5513285f9..a3663f4d5 100644 --- a/docs/cli/test.md +++ b/docs/cli/test.md @@ -1,9 +1,23 @@ Bun ships with a built-in test runner. ```bash -$ bun wiptest +$ bun test ``` +Tests are written in JavaScript or TypeScript with a Jest-like API. + +```ts#math.test.ts +import { expect, test } from "bun:test"; + +test("2 + 2", () => { + expect(2 + 2).toBe(4); +}); +``` + +It's fast. + +{% image src="/images/buntest.jpeg" caption="Bun runs 266 React SSR tests faster than Jest can print its version number." /%} + The runner recursively searches the working directory for files that match the following patterns: - `*.test.{js|jsx|ts|tsx}` @@ -11,10 +25,10 @@ The runner recursively searches the working directory for files that match the f - `*.spec.{js|jsx|ts|tsx}` - `*_spec.{js|jsx|ts|tsx}` -You can filter the set of tests to run by passing additional positional arguments to `wiptest`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported. +You can filter the set of tests to run by passing additional positional arguments to `bun test`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported. ```bash -$ bun wiptest <filter> <filter> ... +$ bun test <filter> <filter> ... ``` <!-- @@ -33,13 +47,13 @@ Consider the following directory structure: To run both `a.test.ts` files: ``` -$ bun wiptest a +$ bun test a ``` To run all tests in the `foo` directory: ``` -$ bun wiptest foo +$ bun test foo ``` Any test file in the directory with an _absolute path_ that contains one of the targets will run. Glob patterns are not yet supported. --> @@ -112,7 +126,7 @@ afterEach(() => { // tests... ``` -Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the *scope* is the current file; in a `describe` block, the scope is the block itself. +Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the _scope_ is the current file; in a `describe` block, the scope is the block itself. ```ts import { expect, test, beforeAll, afterAll } from "bun:test"; |