diff --git a/docs/api/websockets.md b/docs/api/websockets.md index a7439c9725..69ffb403bf 100644 --- a/docs/api/websockets.md +++ b/docs/api/websockets.md @@ -107,6 +107,8 @@ Bun.serve({ Contextual `data` can be attached to a new WebSocket in the `.upgrade()` call. This data is made available on the `ws.data` property inside the WebSocket handlers. +To strongly type `ws.data`, add a `data` property to the `websocket` handler object. This types `ws.data` across all lifecycle hooks. + ```ts type WebSocketData = { createdAt: number; @@ -148,6 +150,10 @@ Bun.serve({ }); ``` +{% callout %} +**Note:** Previously, you could specify the type of `ws.data` using a generic on `Bun.serve`, like `Bun.serve({...})`. This pattern is now deprecated in favor of the `data` property shown above. +{% /callout %} + To connect to this server from the browser, create a new `WebSocket`. ```ts#browser.js diff --git a/docs/bundler/executables.md b/docs/bundler/executables.md index 56f1ac8ed7..097c64f978 100644 --- a/docs/bundler/executables.md +++ b/docs/bundler/executables.md @@ -586,12 +586,41 @@ Codesign support requires Bun v1.2.4 or newer. {% /callout %} +## Code splitting + +Standalone executables support code splitting. Use `--compile` with `--splitting` to create an executable that loads code-split chunks at runtime. + +```bash +$ bun build --compile --splitting ./src/entry.ts --outdir ./build +``` + +{% codetabs %} + +```ts#src/entry.ts +console.log("Entrypoint loaded"); +const lazy = await import("./lazy.ts"); +lazy.hello(); +``` + +```ts#src/lazy.ts +export function hello() { + console.log("Lazy module loaded"); +} +``` + +{% /codetabs %} + +```bash +$ ./build/entry +Entrypoint loaded +Lazy module loaded +``` + ## Unsupported CLI arguments Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags: -- `--outdir` — use `outfile` instead. -- `--splitting` +- `--outdir` — use `outfile` instead (except when using with `--splitting`). - `--public-path` - `--target=node` or `--target=browser` - `--no-bundle` - we always bundle everything into the executable. diff --git a/docs/cli/publish.md b/docs/cli/publish.md index c2d9f75cf1..8b930f290f 100644 --- a/docs/cli/publish.md +++ b/docs/cli/publish.md @@ -84,14 +84,12 @@ $ bun publish --dry-run ### `--tolerate-republish` -The `--tolerate-republish` flag makes `bun publish` exit with code 0 instead of code 1 when attempting to republish over an existing version number. This is useful in automated workflows where republishing the same version might occur and should not be treated as an error. +Exit with code 0 instead of 1 if the package version already exists. Useful in CI/CD where jobs may be re-run. ```sh $ bun publish --tolerate-republish ``` -Without this flag, attempting to publish a version that already exists will result in an error and exit code 1. With this flag, the command will exit successfully even when trying to republish an existing version. - ### `--gzip-level` Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`). diff --git a/docs/install/index.md b/docs/install/index.md index 83a387e9b1..3ecd5c7838 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -89,6 +89,12 @@ $ bun install --linker isolated Isolated installs create strict dependency isolation similar to pnpm, preventing phantom dependencies and ensuring more deterministic builds. For complete documentation, see [Isolated installs](https://bun.com/docs/install/isolated). +To protect against supply chain attacks, set a minimum age (in seconds) for package versions: + +```bash +$ bun install --minimum-release-age 259200 # 3 days +``` + {% details summary="Configuring behavior" %} The default behavior of `bun install` can be configured in `bunfig.toml`: @@ -122,6 +128,12 @@ concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2 # installation strategy: "hoisted" or "isolated" # default: "hoisted" linker = "hoisted" + +# minimum package age in seconds (protects against supply chain attacks) +minimumReleaseAge = 259200 # 3 days + +# exclude packages from age requirement +minimumReleaseAgeExcludes = ["@types/node", "typescript"] ``` {% /details %} diff --git a/docs/install/workspaces.md b/docs/install/workspaces.md index b9e296d051..2e3c9c8238 100644 --- a/docs/install/workspaces.md +++ b/docs/install/workspaces.md @@ -38,9 +38,21 @@ In the root `package.json`, the `"workspaces"` key is used to indicate which sub ``` {% callout %} -**Glob support** — Bun supports full glob syntax in `"workspaces"` (see [here](https://bun.com/docs/api/glob#supported-glob-patterns) for a comprehensive list of supported syntax), _except_ for exclusions (e.g. `!**/excluded/**`), which are not implemented yet. +**Glob support** — Bun supports full glob syntax in `"workspaces"`, including negative patterns (e.g. `!**/excluded/**`). See [here](https://bun.com/docs/api/glob#supported-glob-patterns) for a comprehensive list of supported syntax. {% /callout %} +```json +{ + "name": "my-project", + "version": "1.0.0", + "workspaces": [ + "packages/**", + "!packages/**/test/**", + "!packages/**/template/**" + ] +} +``` + Each workspace has it's own `package.json`. When referencing other packages in the monorepo, semver or workspace protocols (e.g. `workspace:*`) can be used as the version field in your `package.json`. ```json diff --git a/docs/runtime/modules.md b/docs/runtime/modules.md index 83a071ee44..992effa92b 100644 --- a/docs/runtime/modules.md +++ b/docs/runtime/modules.md @@ -174,6 +174,29 @@ import { stuff } from "foo"; The full specification of this algorithm are officially documented in the [Node.js documentation](https://nodejs.org/api/modules.html); we won't rehash it here. Briefly: if you import `from "foo"`, Bun scans up the file system for a `node_modules` directory containing the package `foo`. +### NODE_PATH + +Bun supports `NODE_PATH` for additional module resolution directories: + +```bash +NODE_PATH=./packages bun run src/index.js +``` + +```ts +// packages/foo/index.js +export const hello = "world"; + +// src/index.js +import { hello } from "foo"; +``` + +Multiple paths use the platform's delimiter (`:` on Unix, `;` on Windows): + +```bash +NODE_PATH=./packages:./lib bun run src/index.js # Unix/macOS +NODE_PATH=./packages;./lib bun run src/index.js # Windows +``` + Once it finds the `foo` package, Bun reads the `package.json` to determine how the package should be imported. To determine the package's entrypoint, Bun first reads the `exports` field and checks for the following conditions. ```jsonc#package.json diff --git a/docs/test/configuration.md b/docs/test/configuration.md index edadda2ab6..34d3c9c464 100644 --- a/docs/test/configuration.md +++ b/docs/test/configuration.md @@ -65,6 +65,34 @@ Test files matching this pattern will behave as if the `--concurrent` flag was p The `--concurrent` CLI flag will override this setting when specified, forcing all tests to run concurrently regardless of the glob pattern. +#### randomize + +Run tests in random order to identify tests with hidden dependencies: + +```toml +[test] +randomize = true +``` + +#### seed + +Specify a seed for reproducible random test order. Requires `randomize = true`: + +```toml +[test] +randomize = true +seed = 2444615283 +``` + +#### rerunEach + +Re-run each test file multiple times to identify flaky tests: + +```toml +[test] +rerunEach = 3 +``` + ### Coverage options In addition to the options documented in the [coverage documentation](./coverage.md), the following options are available: diff --git a/docs/test/reporters.md b/docs/test/reporters.md index 9b663301ca..6a3faf6cf1 100644 --- a/docs/test/reporters.md +++ b/docs/test/reporters.md @@ -34,6 +34,15 @@ test/package-json-lint.test.ts: Ran 4 tests across 1 files. [0.66ms] ``` +### Dots Reporter + +The dots reporter shows `.` for passing tests and `F` for failures—useful for large test suites. + +```sh +$ bun test --dots +$ bun test --reporter=dots +``` + ### JUnit XML Reporter For CI/CD environments, Bun supports generating JUnit XML reports. JUnit XML is a widely-adopted format for test results that can be parsed by many CI/CD systems, including GitLab, Jenkins, and others.