diff options
| -rw-r--r-- | .prettierrc | 10 | ||||
| -rw-r--r-- | .vscode/extensions.json | 3 | ||||
| -rw-r--r-- | .vscode/settings.json | 13 | ||||
| -rw-r--r-- | README.md | 353 |
4 files changed, 236 insertions, 143 deletions
diff --git a/.prettierrc b/.prettierrc index d673aada5..eab23fd80 100644 --- a/.prettierrc +++ b/.prettierrc @@ -2,5 +2,13 @@ "arrowParens": "avoid", "printWidth": 120, "trailingComma": "all", - "useTabs": false + "useTabs": false, + "overrides": [ + { + "files": "README.md", + "options": { + "printWidth": 80 + } + } + ] } diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 890a44fb9..0c561c1f9 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -4,6 +4,7 @@ "JarredSumner.zig-unofficial", "esbenp.prettier-vscode", "xaver.clang-format", - "vadimcn.vscode-lldb" + "vadimcn.vscode-lldb", + "yzhang.markdown-all-in-one" ] } diff --git a/.vscode/settings.json b/.vscode/settings.json index 20d8b3001..a77702c2e 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -34,6 +34,19 @@ }, "zig.beforeDebugCmd": "make build-unit ${file} ${filter} ${bin}", "zig.testCmd": "make test ${file} ${filter} ${bin}", + "[markdown]": { + "editor.unicodeHighlight.ambiguousCharacters": false, + "editor.unicodeHighlight.invisibleCharacters": false, + "diffEditor.ignoreTrimWhitespace": false, + "editor.defaultFormatter": "yzhang.markdown-all-in-one", + "editor.formatOnSave": true, + "editor.wordWrap": "on", + "editor.quickSuggestions": { + "comments": "off", + "strings": "off", + "other": "off" + } + }, "lldb.verboseLogging": false, "files.exclude": { "**/.git": true, @@ -73,130 +73,176 @@ bun upgrade --canary ## Table of Contents -- [Install](#install) -- [Using bun.js - a new JavaScript runtime environment](#using-bunjs---a-new-javascript-runtime-environment) - - [Types for bun.js (editor autocomplete)](#types-for-bunjs-editor-autocomplete) - - [Fast paths for Web APIs](#fast-paths-for-web-apis) -- [Using bun as a package manager](#using-bun-as-a-package-manager) -- [Using bun as a task runner](#using-bun-as-a-task-runner) -- [Creating a Discord bot with Bun](#creating-a-discord-bot-with-bun) - - [Application Commands](#application-commands) -- [Using bun with Next.js](#using-bun-with-nextjs) -- [Using bun with single page apps](#using-bun-with-single-page-apps) - - [Using bun with Create React App](#using-bun-with-create-react-app) -- [Using bun with TypeScript](#using-bun-with-typescript) - - [Transpiling TypeScript with Bun](#transpiling-typescript-with-bun) - - [Adding Type Definitions](#adding-type-definitions) -- [Not implemented yet](#not-implemented-yet) - - [Limitations & intended usage](#limitations--intended-usage) - - [Upcoming breaking changes](#upcoming-breaking-changes) -- [Configuration](#configuration) - - [bunfig.toml](#bunfigtoml) +- [bun](#bun) + - [Install](#install) + - [Upgrade](#upgrade) + - [Table of Contents](#table-of-contents) + - [Using bun.js - a new JavaScript runtime environment](#using-bunjs---a-new-javascript-runtime-environment) + - [Types for bun.js (editor autocomplete)](#types-for-bunjs-editor-autocomplete) + - [Fast paths for Web APIs](#fast-paths-for-web-apis) + - [Using bun as a package manager](#using-bun-as-a-package-manager) + - [Using bun as a task runner](#using-bun-as-a-task-runner) + - [Using bun as a WebAssembly runner](#using-bun-as-a-webassembly-runner) + - [Creating a Discord bot with Bun](#creating-a-discord-bot-with-bun) + - [Application Commands](#application-commands) + - [Using bun with Next.js](#using-bun-with-nextjs) + - [Using bun with single-page apps](#using-bun-with-single-page-apps) + - [Using bun with Create React App](#using-bun-with-create-react-app) + - [Using bun with TypeScript](#using-bun-with-typescript) + - [Transpiling TypeScript with Bun](#transpiling-typescript-with-bun) + - [Adding Type Definitions](#adding-type-definitions) + - [Not implemented yet](#not-implemented-yet) + - [Limitations \& intended usage](#limitations--intended-usage) + - [Upcoming breaking changes](#upcoming-breaking-changes) + - [Configuration](#configuration) + - [bunfig.toml](#bunfigtoml) - [Loaders](#loaders) - - [CSS in JS](#css-in-js-bun-dev-only) - - [When `platform` is `browser`](#when-platform-is-browser) - - [When `platform` is `bun`](#when-platform-is-bun) - - [CSS Loader](#css-loader) - - [CSS runtime](#css-runtime) - - [Frameworks](#frameworks) -- [Troubleshooting](#troubleshooting) - - [bun not running on an M1 (or Apple Silicon)](#bun-not-running-on-an-m1-or-apple-silicon) - - [error: Unexpected](#error-unexpected) - - [bun install is stuck](#bun-install-is-stuck) - - [Unzip is required](#unzip-is-required) - - [Debian / Ubuntu / Mint](#debian--ubuntu--mint) - - [RedHat / CentOS / Fedora](#redhat--centos--fedora) - - [Arch / Manjaro](#arch--manjaro) - - [OpenSUSE](#opensuse) -- [Reference](#reference) - - [`bun install`](#bun-install) - - [Configuring bun install with `bunfig.toml`](#configuring-bun-install-with-bunfigtoml) - - [Configuring with environment variables](#configuring-with-environment-variables) - - [Platform-specific dependencies?](#platform-specific-dependencies) - - [Peer dependencies?](#peer-dependencies) - - [Lockfile](#lockfile) - - [Why is it binary?](#why-is-it-binary) - - [How do I inspect it?](#how-do-i-inspect-it) - - [What does the lockfile store?](#what-does-the-lockfile-store) - - [Why is it fast?](#why-is-it-fast) - - [Cache](#cache) - - [npm registry metadata](#npm-registry-metadata) - - [`bun run`](#bun-run) - - [`bun create`](#bun-create) - - [Usage](#usage) - - [Local templates](#local-templates) - - [Flags](#flags) - - [Publishing a new template](#publishing-a-new-template) - - [Testing your new template](#testing-your-new-template) - - [Config](#config) - - [How `bun create` works](#how-bun-create-works) - - [`bun init`](#bun-init) - - [`bun bun`](#bun-bun) - - [Why bundle?](#why-bundle) - - [What is `.bun`?](#what-is-bun) - - [Position-independent code](#position-independent-code) - - [Where is the code?](#where-is-the-code) - - [Advanced](#advanced) - - [What is the module ID hash?](#what-is-the-module-id-hash) - - [`bun upgrade`](#bun-upgrade) - - [`bun completions`](#bun-completions) - - [`bun x`](#bun-x) -- [`Bun.serve` - fast HTTP server](#bunserve---fast-http-server) - - [Usage](#usage-1) - - [HTTPS](#https-with-bunserve) - - [WebSockets](#websockets-with-bunserve) - - [Error handling](#error-handling) -- [`Bun.write` – optimizing I/O](#bunwrite--optimizing-io) -- [`Bun.spawn` - spawn processes](#bunspawn--spawn-a-process) -- [`Bun.which` - find the path to a bin](#bunwhich--find-the-path-to-a-binary) -- [bun:sqlite (SQLite3 module)](#bunsqlite-sqlite3-module) - - [bun:sqlite Benchmark](#bunsqlite-benchmark) - - [Getting started with bun:sqlite](#getting-started-with-bunsqlite) - - [`Database`](#database) - - [Database.prototype.query](#databaseprototypequery) - - [Database.prototype.prepare](#databaseprototypeprepare) - - [Database.prototype.exec & Database.prototype.run](#databaseprototypeexec--databaseprototyperun) - - [Database.prototype.serialize](#databaseprototypeserialize) - - [Database.prototype.loadExtension](#databaseprototypeloadextension) - - [Statement](#statement) - - [Statement.all](#statementall) - - [Statement.values](#statementvalues) - - [Statement.get](#statementget) - - [Statement.run](#statementrun) - - [Statement.finalize](#statementfinalize) - - [Statement.toString()](#statementtostring) - - [Datatypes](#datatypes) -- [`bun:ffi` (Foreign Functions Interface)](#bunffi-foreign-functions-interface) - - [Low-overhead FFI](#low-overhead-ffi) - - [Usage](#usage-2) - - [Supported FFI types (`FFIType`)](#supported-ffi-types-ffitype) - - [Strings (`CString`)](#strings-cstring) - - [Returning a string](#returning-a-string) - - [Function pointers (`CFunction`)](#function-pointers-CFunction) - - [Pointers](#pointers) - - [Passing a pointer](#passing-a-pointer) - - [Reading pointers](#reading-pointers) - - [Not implemented yet](#not-implemented-yet-1) -- [Node-API (napi)](#node-api-napi) -- [`Bun.Transpiler`](#buntranspiler) - - [`Bun.Transpiler.transformSync`](#buntranspilertransformsync) - - [`Bun.Transpiler.transform`](#buntranspilertransform) - - [`Bun.Transpiler.scan`](#buntranspilerscan) - - [`Bun.Transpiler.scanImports`](#buntranspilerscanimports) -- [`Bun.peek` - read a promise same-tick](#bunpeek---read-a-promise-without-resolving-it) -- [`Bun.dns` - lookup a domain](#bundns---lookup-a-domain) -- [Module resolution in Bun](#module-resolution-in-bun) -- [Environment variables](#environment-variables) -- [Credits](#credits) -- [License](#license) -- [Developing bun](#developing-bun) - - [Dev Container (Linux/Windows)](#dev-container-linuxwindows) - - [MacOS](#macos) - - [Build bun (macOS)](#build-bun-macos) - - [Verify it worked (macOS)](#verify-it-worked-macos) - - [Troubleshooting (macOS)](#troubleshooting-macos) - - [Troubleshooting (general)](#troubleshooting-general) -- [vscode-zig](#vscode-zig) + - [CSS in JS (bun dev only)](#css-in-js-bun-dev-only) + - [When `platform` is `browser`](#when-platform-is-browser) + - [When `platform` is `bun`](#when-platform-is-bun) + - [CSS Loader](#css-loader) + - [CSS runtime](#css-runtime) + - [Frameworks](#frameworks) + - [Troubleshooting](#troubleshooting) + - [bun not running on an M1 (or Apple Silicon)](#bun-not-running-on-an-m1-or-apple-silicon) + - [error: Unexpected](#error-unexpected) + - [Unzip is required](#unzip-is-required) + - [Debian / Ubuntu / Mint](#debian--ubuntu--mint) + - [RedHat / CentOS / Fedora](#redhat--centos--fedora) + - [Arch / Manjaro](#arch--manjaro) + - [OpenSUSE](#opensuse) + - [bun install is stuck](#bun-install-is-stuck) + - [Reference](#reference) + - [`bun install`](#bun-install) + - [Configuring bun install with `bunfig.toml`](#configuring-bun-install-with-bunfigtoml) + - [Configuring with environment variables](#configuring-with-environment-variables) + - [Platform-specific dependencies?](#platform-specific-dependencies) + - [Peer dependencies?](#peer-dependencies) + - [Lockfile](#lockfile) + - [Why is it binary?](#why-is-it-binary) + - [How do I inspect it?](#how-do-i-inspect-it) + - [What does the lockfile store?](#what-does-the-lockfile-store) + - [Why is it fast?](#why-is-it-fast) + - [Cache](#cache) + - [Platform-specific backends](#platform-specific-backends) + - [npm registry metadata](#npm-registry-metadata) + - [`bun run`](#bun-run) + - [Run in Bun's JavaScript runtime](#run-in-buns-javascript-runtime) + - [`bun --hot`](#bun---hot) + - [How `bun --hot` works](#how-bun---hot-works) + - [`bun create`](#bun-create) + - [Usage](#usage) + - [Local templates](#local-templates) + - [Flags](#flags) + - [Publishing a new template](#publishing-a-new-template) + - [Testing your new template](#testing-your-new-template) + - [Config](#config) + - [How `bun create` works](#how-bun-create-works) + - [`bun bun`](#bun-bun) + - [Why bundle?](#why-bundle) + - [What is `.bun`?](#what-is-bun) + - [Position-independent code](#position-independent-code) + - [Where is the code?](#where-is-the-code) + - [Advanced](#advanced) + - [What is the module ID hash?](#what-is-the-module-id-hash) + - [`bun upgrade`](#bun-upgrade) + - [Canary builds](#canary-builds) + - [`bun init`](#bun-init) + - [How is `bun init` different than `bun create`?](#how-is-bun-init-different-than-bun-create) + - [`bun completions`](#bun-completions) + - [`bun x` (`bunx`)](#bun-x-bunx) + - [Loader API](#loader-api) + - [Loader API Reference](#loader-api-reference) + - [`builder.onLoad({ filter, namespace?: "optional-namespace" }, callback)`](#builderonload-filter-namespace-optional-namespace--callback) + - [`Bun.serve` - fast HTTP server](#bunserve---fast-http-server) + - [Usage](#usage-1) + - [Error handling](#error-handling) + - [HTTPS with Bun.serve()](#https-with-bunserve) + - [Streaming files with Bun.serve()](#streaming-files-with-bunserve) + - [WebSockets with Bun.serve()](#websockets-with-bunserve) + - [ServerWebSocket vs WebSocket](#serverwebsocket-vs-websocket) + - [Headers](#headers) + - [Publish/subscribe](#publishsubscribe) + - [Backpressure](#backpressure) + - [Callbacks are per server instead of per socket](#callbacks-are-per-server-instead-of-per-socket) + - [`Bun.spawn` – spawn a process](#bunspawn--spawn-a-process) + - [`Bun.which` – find the path to a binary](#bunwhich--find-the-path-to-a-binary) + - [`Bun.listen` \& `Bun.connect` - TCP/TLS sockets](#bunlisten--bunconnect---tcptls-sockets) + - [Benchmark-driven API design](#benchmark-driven-api-design) + - [Hot-reloading TCP servers \& clients](#hot-reloading-tcp-servers--clients) + - [No buffering](#no-buffering) + - [`Bun.dns` - lookup a domain](#bundns---lookup-a-domain) + - [`Bun.peek` - read a promise without resolving it](#bunpeek---read-a-promise-without-resolving-it) + - [`Bun.write` – optimizing I/O](#bunwrite--optimizing-io) + - [bun:sqlite (SQLite3 module)](#bunsqlite-sqlite3-module) + - [bun:sqlite Benchmark](#bunsqlite-benchmark) + - [Getting started with bun:sqlite](#getting-started-with-bunsqlite) + - [`Database`](#database) + - [Database.prototype.query](#databaseprototypequery) + - [Database.prototype.prepare](#databaseprototypeprepare) + - [Database.prototype.exec \& Database.prototype.run](#databaseprototypeexec--databaseprototyperun) + - [Database.prototype.transaction](#databaseprototypetransaction) + - [Database.prototype.serialize](#databaseprototypeserialize) + - [Database.prototype.loadExtension](#databaseprototypeloadextension) + - [Statement](#statement) + - [Statement.all](#statementall) + - [Statement.values](#statementvalues) + - [Statement.get](#statementget) + - [Statement.run](#statementrun) + - [Statement.finalize](#statementfinalize) + - [Statement.toString()](#statementtostring) + - [Datatypes](#datatypes) + - [`bun:ffi` (Foreign Functions Interface)](#bunffi-foreign-functions-interface) + - [Low-overhead FFI](#low-overhead-ffi) + - [Usage](#usage-2) + - [Supported FFI types (`FFIType`)](#supported-ffi-types-ffitype) + - [Strings (`CString`)](#strings-cstring) + - [Returning a string](#returning-a-string) + - [Function pointers (`CFunction`)](#function-pointers-cfunction) + - [Callbacks (`JSCallback`)](#callbacks-jscallback) + - [Pointers](#pointers) + - [Passing a pointer](#passing-a-pointer) + - [Reading pointers](#reading-pointers) + - [Not implemented yet](#not-implemented-yet-1) + - [Node-API (napi)](#node-api-napi) + - [`Bun.Transpiler`](#buntranspiler) + - [`Bun.Transpiler.transformSync`](#buntranspilertransformsync) + - [`Bun.Transpiler.transform`](#buntranspilertransform) + - [`Bun.Transpiler.scan`](#buntranspilerscan) + - [`Bun.Transpiler.scanImports`](#buntranspilerscanimports) + - [Module resolution in Bun](#module-resolution-in-bun) + - [Module loading](#module-loading) + - [Module resolution](#module-resolution) + - [Bun's Module Resolution Algorithm](#buns-module-resolution-algorithm) + - [Resolving packages](#resolving-packages) + - [Prefer offline](#prefer-offline) + - [Prefer latest](#prefer-latest) + - [Resolving modules](#resolving-modules) + - [Frequently asked questions](#frequently-asked-questions) + - [Environment variables](#environment-variables) + - [Profiling Bun](#profiling-bun) + - [Benchmarking `Bun.serve`](#benchmarking-bunserve) + - [Measuring memory usage](#measuring-memory-usage) + - [JavaScript heap stats](#javascript-heap-stats) + - [JavaScript heap snapshot](#javascript-heap-snapshot) + - [Native heap stats](#native-heap-stats) + - [Credits](#credits) + - [License](#license) + - [Developing bun](#developing-bun) + - [Dev Container (Linux/Windows)](#dev-container-linuxwindows) + - [Visual Studio Code](#visual-studio-code) + - [Other editors and CLI](#other-editors-and-cli) + - [In the dev container](#in-the-dev-container) + - [MacOS](#macos) + - [Install Zig (macOS)](#install-zig-macos) + - [Build bun (macOS)](#build-bun-macos) + - [Verify it worked (macOS)](#verify-it-worked-macos) + - [JavaScript builtins](#javascript-builtins) + - [Code generation scripts](#code-generation-scripts) + - [Modifying ESM core modules](#modifying-esm-core-modules) + - [Troubleshooting (macOS)](#troubleshooting-macos) + - [vscode-zig](#vscode-zig) + - [Troubleshooting (general)](#troubleshooting-general) ## Using bun.js - a new JavaScript runtime environment @@ -518,15 +564,15 @@ bun By default, `bun` will look for any HTML files in the `public` directory and serve that. For browsers navigating to the page, the `.html` file extension is optional in the URL, and `index.html` will automatically rewrite for the directory. Here are examples of routing from `public/` and how they’re matched: -| Dev Server URL | File Path | -|----------------|-----------| -| /dir | public/dir/index.html | -| / | public/index.html | -| /index | public/index.html | -| /hi | public/hi.html | -| /file | public/file.html | +| Dev Server URL | File Path | +| ----------------- | ----------------------- | +| /dir | public/dir/index.html | +| / | public/index.html | +| /index | public/index.html | +| /hi | public/hi.html | +| /file | public/file.html | | /font/Inter.woff2 | public/font/Inter.woff2 | -| /hello | public/index.html | +| /hello | public/index.html | If `public/index.html` exists, it becomes the default page instead of a 404 page, unless that pathname has a file extension. @@ -1451,7 +1497,7 @@ globalThis.reloadCount = reloadCount + 1; const reloadServer = (globalThis.reloadServer ||= (() => { let server; - return (handler) => { + return handler => { if (server) { // call `server.reload` to reload the server server.reload(handler); @@ -1863,20 +1909,44 @@ This command installs completions for `zsh` and/or `fish`. It runs automatically If you want to copy the completions manually, run `bun completions > path-to-file`. If you know the completions directory to install them to, run `bun completions /path/to/directory`. -### `bun x` +### `bun x` (`bunx`) -This command runs a given binary from `npm`. It will look for the binary to run in any installed modules in the current file tree, and install the package in a temporary directory to run if its not available. +This command runs a given binary from `npm`. It will look for the executable to run in any installed modules in the current file tree, and install the package in a temporary directory to run if its not available. + +> Run vendor package executable -> Run vendor package ```bash bun x vendor-package ``` -> Run a specific version of vendor package +Bun also provides a shortened alias `bunx` which you can use instead. + +> Run package executable with `bunx` alias + +```bash +bunx vendor-package +``` + +> Run a specific version of package executable + ```bash bun x vendor-package@1.0.2 ``` +**NOTE: By default, `bun x` currently runs JS scripts in `Node`, but you can force running them in `Bun` by appending the `--bun` flag to the `bun` command. This will be changed in the future when more Node compatibility is achieved.** + +> Force a package executable to run in Bun + +```bash +bun --bun x vendor-package +``` + +or: + +```bash +bunx --bun vendor-package +``` + ## Loader API Bun v0.1.11 introduces custom loaders. @@ -1900,7 +1970,7 @@ plugin({ const { load } = require("js-yaml"); const { readFileSync } = require("fs"); // Run this function on any import that ends with .yaml or .yml - builder.onLoad({ filter: /\.(yaml|yml)$/ }, (args) => { + builder.onLoad({ filter: /\.(yaml|yml)$/ }, args => { // Read the YAML file from disk const text = readFileSync(args.path, "utf8"); @@ -3342,7 +3412,7 @@ db.exec( ); const insert = db.prepare("INSERT INTO cats (name, age) VALUES ($name, $age)"); -const insertMany = db.transaction((cats) => { +const insertMany = db.transaction(cats => { for (const cat of cats) insert.run(cat); }); @@ -3369,11 +3439,11 @@ const newExpense = db.prepare( "INSERT INTO expenses (note, dollars) VALUES (?, ?)", ); const insert = db.prepare("INSERT INTO cats (name, age) VALUES ($name, $age)"); -const insertMany = db.transaction((cats) => { +const insertMany = db.transaction(cats => { for (const cat of cats) insert.run(cat); }); -const adopt = db.transaction((cats) => { +const adopt = db.transaction(cats => { newExpense.run("adoption fees", 20); insertMany(cats); // nested transaction }); @@ -4023,7 +4093,7 @@ When you're done with a JSCallback, you should call `close()` to free the memory For a slight performance boost, directly pass `JSCallback.prototype.ptr` instead of the `JSCallback` object: ```ts -const onResolve = new JSCallback((arg) => arg === 42, { +const onResolve = new JSCallback(arg => arg === 42, { returns: "bool", args: ["i32"], }); @@ -5158,6 +5228,7 @@ On fish that looks like `fish_add_path (brew --prefix llvm@15)/bin` #### Install Zig (macOS) Install the version of Zig referenced in the [`Dockerfile`](./Dockerfile) using [zigup](https://github.com/marler8997/zigup). For example: + ```bash zigup 0.11.0-dev.1393+38eebf3c4 ``` |