diff options
Diffstat (limited to 'docs/runtime')
| -rw-r--r-- | docs/runtime/bun-apis.md | 79 | ||||
| -rw-r--r-- | docs/runtime/configuration.md | 116 | ||||
| -rw-r--r-- | docs/runtime/jsx.md | 289 | ||||
| -rw-r--r-- | docs/runtime/modules.md | 2 | ||||
| -rw-r--r-- | docs/runtime/nodejs-apis.md | 4 |
5 files changed, 412 insertions, 78 deletions
diff --git a/docs/runtime/bun-apis.md b/docs/runtime/bun-apis.md index 0cfdf61fb..c4cd534e7 100644 --- a/docs/runtime/bun-apis.md +++ b/docs/runtime/bun-apis.md @@ -1,4 +1,16 @@ -Bun implements a set of native APIs on the `Bun` global object and through a number of built-in modules. These APIs represent the canonical "Bun-native" way to perform some common development tasks. They are all heavily optimized for performance. Click the link in the left column to view the associated documentation. +Bun implements a set of native APIs on the `Bun` global object and through a number of built-in modules. These APIs are heavily optimized and represent the canonical "Bun-native" way to implement some common functionality. + +Bun strives to implement standard Web APIs wherever possible. Bun introduces new APIs primarily for server-side tasks where no standard exists, such as file I/O and starting an HTTP server. In these cases, Bun's approach still builds atop standard APIs like `Blob`, `URL`, and `Request`. + +```ts +Bun.serve({ + fetch(req: Request) { + return new Response("Success!"); + }, +}); +``` + +Click the link in the right column to jump to the associated documentation. {% table %} @@ -7,38 +19,53 @@ Bun implements a set of native APIs on the `Bun` global object and through a num --- -- [HTTP](/docs/api/http) -- `Bun.serve` +- HTTP server +- [`Bun.serve`](/docs/api/http#bun-serve) + +--- + +- Bundler +- [`Bun.build`](/docs/bundler) + +--- + +- File I/O +- [`Bun.file`](/docs/api/file-io#reading-files-bun-file) [`Bun.write`](/docs/api/file-io#writing-files-bun-write) --- -- [File I/O](/docs/api/file-io) -- `Bun.file` `Bun.write` +- Child processes +- [`Bun.spawn`](/docs/api/spawn#spawn-a-process-bun-spawn) [`Bun.spawnSync`](/docs/api/spawn#blocking-api-bun-spawnsync) --- -- [Processes](/docs/api/spawn) -- `Bun.spawn` `Bun.spawnSync` +- TCP +- [`Bun.listen`](/docs/api/tcp#start-a-server-bun-listen) [`Bun.connect`](/docs/api/tcp#start-a-server-bun-listen) --- -- [TCP](/docs/api/tcp) -- `Bun.listen` `Bun.connect` +- Transpiler +- [`Bun.Transpiler`](/docs/api/transpiler) --- -- [Transpiler](/docs/api/transpiler) -- `Bun.Transpiler` +- Routing +- [`Bun.FileSystemRouter`](/docs/api/file-system-router) --- -- [Routing](/docs/api/file-system-router) -- `Bun.FileSystemRouter` +- HTML Rewriting +- [`HTMLRewriter`](/docs/api/html-rewriter) --- -- [HTMLRewriter](/docs/api/html-rewriter) -- `HTMLRewriter` +- Hashing +- [`Bun.hash`](/docs/api/hashing#bun-hash) [`Bun.CryptoHasher`](/docs/api/hashing#bun-cryptohasher) + +--- + +- import.meta +- [`import.meta`](/docs/api/import-meta) --- @@ -47,29 +74,27 @@ Bun implements a set of native APIs on the `Bun` global object and through a num --- --> -- [Utils](/docs/api/utils) -- `Bun.peek` `Bun.which` +- SQLite +- [`bun:sqlite`](/docs/api/sqlite) --- -- [SQLite](/docs/api/sqlite) -- `bun:sqlite` +- FFI +- [`bun:ffi`](/docs/api/ffi) --- -- [FFI](/docs/api/ffi) -- `bun:ffi` +- Testing +- [`bun:test`](/docs/cli/test) --- -- [Testing](/docs/api/test) -- `bun:test` +- Node-API +- [`Node-API`](/docs/api/node-api) --- -- [Node-API](/docs/api/node-api) -- `Node-API` - ---- +- Utilities +- [`Bun.version`](/docs/api/utils#bun-version) [`Bun.revision`](/docs/api/utils#bun-revision) [`Bun.env`](/docs/api/utils#bun-env) [`Bun.main`](/docs/api/utils#bun-main) [`Bun.sleep()`](/docs/api/utils#bun-sleep) [`Bun.sleepSync()`](/docs/api/utils#bun-sleepsync) [`Bun.which()`](/docs/api/utils#bun-which) [`Bun.peek()`](/docs/api/utils#bun-peek) [`Bun.openInEditor()`](/docs/api/utils#bun-openineditor) [`Bun.deepEquals()`](/docs/api/utils#bun-deepequals) [`Bun.escapeHTML()`](/docs/api/utils#bun-escapehtlm) [`Bun.enableANSIColors()`](/docs/api/utils#bun-enableansicolors) [`Bun.fileURLToPath()`](/docs/api/utils#bun-fileurltopath) [`Bun.pathToFileURL()`](/docs/api/utils#bun-pathtofileurl) [`Bun.gzipSync()`](/docs/api/utils#bun-gzipsync) [`Bun.gunzipSync()`](/docs/api/utils#bun-gunzipsync) [`Bun.deflateSync()`](/docs/api/utils#bun-deflatesync) [`Bun.inflateSync()`](/docs/api/utils#bun-inflatesync) [`Bun.inspect()`](/docs/api/utils#bun-inspect) [`Bun.nanoseconds()`](/docs/api/utils#bun-nanoseconds) [`Bun.readableStreamTo*()`](/docs/api/utils#bun-readablestreamto) [`Bun.resolveSync()`](/docs/api/utils#bun-resolvesync) {% /table %} diff --git a/docs/runtime/configuration.md b/docs/runtime/configuration.md index 9ea896edb..83a6ae37f 100644 --- a/docs/runtime/configuration.md +++ b/docs/runtime/configuration.md @@ -19,7 +19,77 @@ If both a global and local `bunfig` are detected, the results are shallow-merged - `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`: Bun occasionally requires a directory to store intermediate assets during bundling or other operations. If unset, `TMPDIR` defaults to the platform-specific temporary directory (on Linux, `/tmp` and on macOS `/private/tmp`). -## Configure `bun install` +## Runtime + +```toml +# scripts to run before `bun run`ning a file or script +# useful for registering plugins +preload = ["./preload.ts"] + +# equivalent to corresponding tsconfig compilerOptions +jsx = "react" +jsxFactory = "h" +jsxFragment = "Fragment" +jsxImportSource = "react" + +# Set a default framework to use +# By default, Bun will look for an npm package like `bun-framework-${framework}`, followed by `${framework}` +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" } + +[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" +# - "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 +``` + +### Debugging + +```toml +[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" +``` + +## Test runner + +```toml +[test] +# setup scripts to run before all test files +preload = ["./setup.ts"] +``` + +## Package manager 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/runtime/configuration). @@ -120,7 +190,9 @@ save = true print = "yarn" ``` -## Configure `bun dev` +## Dev server (`bun dev`) + +{% The `bun dev` command is likely to change soon and will likely be deprecated in an upcoming release. We recommend %} Here is an example: @@ -128,17 +200,6 @@ Here is an example: # 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" @@ -154,33 +215,4 @@ entryPoints = ["./app/index.ts"] # 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 ``` diff --git a/docs/runtime/jsx.md b/docs/runtime/jsx.md index 1ace6e367..ae0a319db 100644 --- a/docs/runtime/jsx.md +++ b/docs/runtime/jsx.md @@ -12,14 +12,291 @@ function Component(props: {message: string}) { console.log(<Component message="Hello world!" />); ``` -Bun implements special logging for JSX to make debugging easier. +## Configuration -```bash -$ bun run react.tsx -<Component message="Hello world!" /> +Bun reads your `tsconfig.json` or `jsconfig.json` configuration files to determines how to perform the JSX transform internally. To avoid using either of these, the following options can also be defined in [`bunfig.json`](/docs/runtime/configuration). + +The following compiler options are respected. + +### [`jsx`](https://www.typescriptlang.org/tsconfig#jsx) + +How JSX constructs are transformed into vanilla JavaScript internally. The table below lists the possible values of `jsx`, along with their transpilation of the following simple JSX component: + +```tsx +<Box width={5}>Hello</Box> +``` + +{% table %} + +- Compiler options +- Transpiled output + +--- + +- ```json + { + "jsx": "react" + } + ``` + +- ```tsx + import { createElement } from "react"; + createElement("Box", { width: 5 }, "Hello"); + ``` + +--- + +- ```json + { + "jsx": "react-jsx" + } + ``` + +- ```tsx + import { jsx } from "react/jsx-runtime"; + jsx("Box", { width: 5 }, "Hello"); + ``` + +--- + +- ```json + { + "jsx": "react-jsxdev" + } + ``` + +- ```tsx + import { jsxDEV } from "react/jsx-dev-runtime"; + jsxDEV("Box", { width: 5, children: "Hello" }, undefined, false, undefined, this); + ``` + + The `jsxDEV` variable name is a convention used by React. The `DEV` suffix is a visible way to indicate that the code is intended for use in development. The development version of React is slowers and includes additional validity checks & debugging tools. + +--- + +- ```json + { + "jsx": "preserve" + } + ``` + +- ```tsx + // JSX is not transpiled + // "preserve" is not supported by Bun currently + <Box width={5}>Hello</Box> + ``` + +{% /table %} + +<!-- {% table %} + +- `react` +- `React.createElement("Box", {width: 5}, "Hello")` + +--- + +- `react-jsx` +- `jsx("Box", {width: 5}, "Hello")` + +--- + +- `react-jsxdev` +- `jsxDEV("Box", {width: 5}, "Hello", void 0, false)` + +--- + +- `preserve` +- `<Box width={5}>Hello</Box>` Left as-is; not yet supported by Bun. + +{% /table %} --> + +### [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory) + +{% callout %} +**Note** β Only applicable when `jsx` is `react`. +{% /callout %} + +The function name used to represent JSX constructs. Default value is `"createElement"`. This is useful for libraries like [Preact](https://preactjs.com/) that use a different function name (`"h"`). + +{% table %} + +- Compiler options +- Transpiled output + +--- + +- ```json + { + "jsx": "react", + "jsxFactory": "h" + } + ``` + +- ```tsx + import { createhElement } from "react"; + h("Box", { width: 5 }, "Hello"); + ``` + +{% /table %} + +### [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory) + +{% callout %} +**Note** β Only applicable when `jsx` is `react`. +{% /callout %} + +The function name used to represent [JSX fragments](https://react.dev/reference/react/Fragment) such as `<>Hello</>`; only applicable when `jsx` is `react`. Default value is `"Fragment"`. + +{% table %} + +- Compiler options +- Transpiled output + +--- + +- ```json + { + "jsx": "react", + "jsxFactory": "myjsx", + "jsxFragmentFactory": "MyFragment" + } + ``` + +- ```tsx + // input + <>Hello</>; + + // output + import { myjsx, MyFragment } from "react"; + createElement("Box", { width: 5 }, "Hello"); + ``` + +{% /table %} + +### [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource) + +{% callout %} +**Note** β Only applicable when `jsx` is `react-jsx` or `react-jsxdev`. +{% /callout %} + +The module from which the component factory function (`createElement`, `jsx`, `jsxDEV`, etc) will be imported. Default value is `"react"`. This will typically be necessary when using a component library like Preact. + +{% table %} + +- Compiler options +- Transpiled output + +--- + +- ```jsonc + { + "jsx": "react" + // jsxImportSource is not defined + // default to "react" + } + ``` + +- ```tsx + import { jsx } from "react/jsx-runtime"; + jsx("Box", { width: 5, children: "Hello" }); + ``` + +--- + +- ```jsonc + { + "jsx": "react-jsx", + "jsxImportSource": "preact" + } + ``` + +- ```tsx + import { jsx } from "preact/jsx-runtime"; + jsx("Box", { width: 5, children: "Hello" }); + ``` + +--- + +- ```jsonc + { + "jsx": "react-jsxdev", + "jsxImportSource": "preact" + } + ``` + +- ```tsx + // /jsx-runtime is automatically appended + import { jsxDEV } from "preact/jsx-dev-runtime"; + jsxDEV("Box", { width: 5, children: "Hello" }, undefined, false, undefined, this); + ``` + +{% /table %} + +### JSX pragma + +All of these values can be set on a per-file basis using _pragmas_. A pragma is a special comment that sets a compiler option in a particular file. + +{% table %} + +- Pragma +- Equivalent config + +--- + +- ```ts + // @jsx h + ``` + +- ```jsonc + { + "jsxFactory": "h" + } + ``` + +--- + +- ```ts + // @jsxFrag MyFragment + ``` +- ```jsonc + { + "jsxFragmentFactory": "MyFragment" + } + ``` + +--- + +- ```ts + // @jsxImportSource preact + ``` +- ```jsonc + { + "jsxImportSource": "preact" + } + ``` + +{% /table %} + +## Logging + +Bun implements special logging for JSX to make debugging easier. Given the following file: + +```tsx#index.tsx +import { Stack, UserCard } from "./components"; + +console.log( + <Stack> + <UserCard name="Dom" bio="Street racer and Corona lover" /> + <UserCard name="Jakob" bio="Super spy and Dom's secret brother" /> + </Stack> +); ``` -<!-- ### Prop punning +Bun will pretty-print the component tree when logged: + +{% image src="https://github.com/oven-sh/bun/assets/3084745/d29db51d-6837-44e2-b8be-84fc1b9e9d97" / %} + +## Prop punning The Bun runtime also supports "prop punning" for JSX. This is a shorthand syntax useful for assigning a variable to a prop with the same name. @@ -32,4 +309,4 @@ function Div(props: {className: string;}) { // with punning return <div {className} />; } -``` --> +``` diff --git a/docs/runtime/modules.md b/docs/runtime/modules.md index 6c33f7336..da9bc9253 100644 --- a/docs/runtime/modules.md +++ b/docs/runtime/modules.md @@ -121,7 +121,7 @@ Bun respects subpath [`"exports"`](https://nodejs.org/api/packages.html#subpath- "name": "foo", "exports": { ".": "./index.js", - "./package.json": "./package.json" # subpath + "./package.json": "./package.json" // subpath } } ``` diff --git a/docs/runtime/nodejs-apis.md b/docs/runtime/nodejs-apis.md index a4256077c..9a7cf070a 100644 --- a/docs/runtime/nodejs-apis.md +++ b/docs/runtime/nodejs-apis.md @@ -104,8 +104,8 @@ This page is updated regularly to reflect compatibility status of the latest ver --- - {% anchor id="node_https" %} [`node:https`](https://nodejs.org/api/https.html) {% /anchor %} -- π‘ -- See `node:http`. +- π’ +- Fully implemented. --- |