diff options
Diffstat (limited to 'docs/project')
| -rw-r--r-- | docs/project/benchmarking.md | 15 | ||||
| -rw-r--r-- | docs/project/configuration.md | 182 |
2 files changed, 8 insertions, 189 deletions
diff --git a/docs/project/benchmarking.md b/docs/project/benchmarking.md index b9672f325..96b06b640 100644 --- a/docs/project/benchmarking.md +++ b/docs/project/benchmarking.md @@ -12,17 +12,18 @@ To precisely measure time, Bun offers two runtime APIs functions: When writing your own benchmarks, it's important to choose the right tool. - For microbenchmarks, a great general-purpose tool is [`mitata`](https://github.com/evanwashere/mitata). -- For load testing, you *must use* an HTTP benchmarking tool that is at least as fast as `Bun.serve()`, or your results will be skewed. Some popular Node.js-based benchmarking tools like [`autocannon`](https://github.com/mcollina/autocannon) are not fast enough. We recommend one of the following: +- For load testing, you _must use_ an HTTP benchmarking tool that is at least as fast as `Bun.serve()`, or your results will be skewed. Some popular Node.js-based benchmarking tools like [`autocannon`](https://github.com/mcollina/autocannon) are not fast enough. We recommend one of the following: - [`bombardier`](https://github.com/codesenberg/bombardier) - [`oha`](https://github.com/hatoo/oha) - [`http_load_test`](https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c) -- For benchmarking scripts or CLI commands, we recommend [`hyperfine`](https://github.com/sharkdp/hyperfine). It's an easy way to compare - +- For benchmarking scripts or CLI commands, we recommend [`hyperfine`](https://github.com/sharkdp/hyperfine). ## Measuring memory usage Bun has two heaps. One heap is for the JavaScript runtime and the other heap is for everything else. +{% anchor id="bunjsc" /%} + ### JavaScript heap stats The `bun:jsc` module exposes a few functions for measuring memory usage: @@ -31,7 +32,9 @@ The `bun:jsc` module exposes a few functions for measuring memory usage: import { heapStats } from "bun:jsc"; console.log(heapStats()); ``` + {% details summary="View example statistics" %} + ```ts { heapSize: 1657575, @@ -134,6 +137,7 @@ console.log(heapStats()); } } ``` + {% /details %} JavaScript is a garbage-collected language, not reference counted. It's normal and correct for objects to not be freed immediately in all cases, though it's not normal for objects to never be freed. @@ -141,7 +145,7 @@ JavaScript is a garbage-collected language, not reference counted. It's normal a Tp force garbage collection to run manually: ```js -Bun.gc(true); // synchronous +Bun.gc(true); // synchronous Bun.gc(false); // asynchronous ``` @@ -161,15 +165,12 @@ To view the snapshot, open the `heap.json` file in Safari's Developer Tools (or 3. Click "JavaScript Allocations" in the menu on the left. It might not be visible until you click the pencil icon to show all the timelines 4. Click "Import" and select your heap snapshot JSON - {% image alt="Import heap json" src="https://user-images.githubusercontent.com/709451/204428943-ba999e8f-8984-4f23-97cb-b4e3e280363e.png" caption="Importing a heap snapshot" /%} Once imported, you should see something like this: - {% image alt="Viewing heap snapshot in Safari" src="https://user-images.githubusercontent.com/709451/204429337-b0d8935f-3509-4071-b991-217794d1fb27.png" caption="Viewing heap snapshot in Safari Dev Tools" /%} - ### Native heap stats Bun uses mimalloc for the other heap. To report a summary of non-JavaScript memory usage, set the `MIMALLOC_SHOW_STATS=1` environment variable. and stats will print on exit. diff --git a/docs/project/configuration.md b/docs/project/configuration.md deleted file mode 100644 index c70689b94..000000000 --- a/docs/project/configuration.md +++ /dev/null @@ -1,182 +0,0 @@ -## Environment variables - -- `GOMAXPROCS`: For `bun bun`, this sets the maximum number of threads to use. If you’re experiencing an issue with `bun bun`, try setting `GOMAXPROCS=1` to force Bun to run single-threaded -- `DISABLE_BUN_ANALYTICS=1` this disables Bun's analytics. Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it’s not a lot of data -- `TMPDIR`: Before `bun bun` completes, it stores the new `.bun` in `$TMPDIR`. If unset, `TMPDIR` defaults to the platform-specific temporary directory (on Linux, `/tmp` and on macOS `/private/tmp`) - -## `bunfig.toml` - -Bun's configuration file is called `bunfig.toml`. Configuring with `bunfig.toml` is optional. Bun aims to be zero-configuration out of the box, but is also highly configurable for advanced use cases.. - -Your `bunfig.toml` should live in your project root alongside `package.json`. You can also create a global configuration file at the following paths: - -- `$HOME/.bunfig.toml` -- `$XDG_CONFIG_HOME/.bunfig.toml` - -If both a global and local `bunfig` are detected, the results are shallow-merged, with local overridding global. CLI flags will override `bunfig` setting where applicable. - -## Configure `bun install` - -Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured in [`bunfig.toml`](/docs/project/configuration). - -### Default flags - -The following settings modify the core behavior of Bun's package management commands. **The default values are shown below.** - -```toml -[install] - -# whether to install optionalDependencies -optional = true - -# whether to install devDependencies -dev = true - -# whether to install peerDependencies -peer = false - -# equivalent to `--production` flag -production = false - -# equivalent to `--dry-run` flag -dryRun = false -``` - -### Registries - -The default registry is `https://registry.npmjs.org/`. This can be globally configured in `bunfig.toml`: - -```toml -[install] -# set default registry as a string -registry = "https://registry.npmjs.org" -# set a token -registry = { url = "https://registry.npmjs.org", token = "123456" } -# set a username/password -registry = "https://username:password@registry.npmjs.org" -``` - -To configure scoped registries: - -```toml -[install.scopes] -# registry as string -myorg1 = "https://username:password@registry.myorg.com/" - -# registry with username/password -# you can reference environment variables -myorg12 = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" } - -# registry with token -myorg3 = { token = "$npm_token", url = "https://registry.myorg.com/" } -``` - -### Cache - -To configure caching behavior: - -```toml -[install] -# where `bun install --global` installs packages -globalDir = "~/.bun/install/global" - -# where globally-installed package bins are linked -globalBinDir = "~/.bun/bin" - -[install.cache] -# the directory to use for the cache -dir = "~/.bun/install/cache" - -# when true, don't load from the global cache. -# Bun may still write to node_modules/.cache -disable = false - -# when true, always resolve the latest versions from the registry -disableManifest = false -``` - -### Lockfile - -To configure lockfile behavior: - -```toml {% disabled %} -[install.lockfile] - -# path to read bun.lockb from -path = "bun.lockb" - -# path to save bun.lockb to -savePath = "bun.lockb" - -# 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" -``` - -## Configure `bun dev` - -Here is an example: - -```toml -# Set a default framework to use -# By default, Bun will look for an npm package like `bun-framework-${framework}`, followed by `${framework}` -framework = "next" -logLevel = "debug" - -# publicDir = "public" -# external = ["jquery"] - -[macros] -# Remap any import like this: -# import {graphql} from 'react-relay'; -# To: -# import {graphql} from 'macro:bun-macro-relay'; -react-relay = { "graphql" = "bun-macro-relay" } - -[bundle] -saveTo = "node_modules.bun" -# Don't need this if `framework` is set, but showing it here as an example anyway -entryPoints = ["./app/index.ts"] - -[bundle.packages] -# If you're bundling packages that do not actually live in a `node_modules` folder or do not have the full package name in the file path, you can pass this to bundle them anyway -"@bigapp/design-system" = true - -[dev] -# Change the default port from 3000 to 5000 -# Also inherited by Bun.serve -port = 5000 - -[define] -# Replace any usage of "process.env.bagel" with the string `lox`. -# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS. -# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing. -"process.env.bagel" = "'lox'" - -[loaders] -# When loading a .bagel file, run the JS parser -".bagel" = "js" - -[debug] -# When navigating to a blob: or src: link, open the file in your editor -# If not, it tries $EDITOR or $VISUAL -# If that still fails, it will try Visual Studio Code, then Sublime Text, then a few others -# This is used by Bun.openInEditor() -editor = "code" - -# List of editors: -# - "subl", "sublime" -# - "vscode", "code" -# - "textmate", "mate" -# - "idea" -# - "webstorm" -# - "nvim", "neovim" -# - "vim","vi" -# - "emacs" -# - "atom" -# If you pass it a file path, it will open with the file path instead -# It will recognize non-GUI editors, but I don't think it will work yet -``` |