mirrors/bun.sh
1
0
Fork 0
mirror of https://github.com/oven-sh/bun synced 2026-02-02 15:08:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Minor fixes and improvements (#25284)

Browse Source 
This PR addresses several issues opened for the docs:

- Add callout for SQLite caching behavior between prepare() and query()
- Fix SQLite types and fix deprecated exec to run
- Fix Secrets API example
- Update SolidStart guide
- Add bun upgrade guide
- Prefer `process.versions.bun` over `typeof Bun` for detection
- Document complete `bunx` flags
- Improve Nitro preset documentation for Nuxt

Fixes #23165, #24424, #24294, #25175, #18433, #16804, #22967, #22527,
#10560, #14744
This commit is contained in:
Lydia Hallie
2025-12-01 15:32:08 -06:00
committed by GitHub
parent 9c420c9eff
commit dce7a02f4d
9 changed files with 234 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docs.json
View File

@@ -326,6 +326,7 @@
"group": "Utilities",
"icon": "wrench",
"pages": [
"/guides/util/upgrade",
"/guides/util/detect-bun",
"/guides/util/version",
"/guides/util/hash-a-password",

6
docs/guides/ecosystem/nuxt.mdx
View File

@@ -74,6 +74,12 @@ export default defineNuxtConfig({
});
```
Alternatively, you can set the preset via environment variable:
```sh terminal icon="terminal"
NITRO_PRESET=bun bun run build
```
<Note>
Some packages provide Bun-specific exports that Nitro will not bundle correctly using the default preset. In this
case, you need to use Bun preset so that the packages will work correctly in production builds.

68
docs/guides/ecosystem/solidstart.mdx
View File

@@ -4,63 +4,59 @@ sidebarTitle: "SolidStart with Bun"
mode: center
---
<Warning>
SolidStart currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a
project and install dependencies, but it uses Node.js to run the dev server.
</Warning>
---
Initialize a SolidStart app with `create-solid`.
Initialize a SolidStart app with `create-solid`. You can specify the `--solidstart` flag to create a SolidStart project, and `--ts` for TypeScript support. When prompted for a template, select `basic` for a minimal starter app.
```sh terminal icon="terminal"
bun create solid my-app
bun create solid my-app --solidstart --ts
```
```txt
create-solid version 0.2.31
Welcome to the SolidStart setup wizard!
There are definitely bugs and some feature might not work yet.
If you encounter an issue, have a look at
https://github.com/solidjs/solid-start/issues and open a new one,
if it is not already tracked.
✔ Which template do you want to use? › todomvc
✔ Server Side Rendering? … yes
✔ Use TypeScript? … yes
cloned solidjs/solid-start#main to /path/to/my-app/.solid-start
✔ Copied project files
┌
Create-Solid v0.6.11
│
◇ Project Name
│ my-app
│
◇ Which template would you like to use?
│ basic
│
◇ Project created 🎉
│
◇ To get started, run: ─╮
│ │
│ cd my-app │
│ bun install │
│ bun dev │
│ │
├────────────────────────╯
```
---
As instructed by the `create-solid` CLI, let's install our dependencies.
As instructed by the `create-solid` CLI, install the dependencies.
```sh terminal icon="terminal"
cd my-app
bun install
```
---
Then run the development server.
Then run the development server with `bun dev`.
```sh terminal icon="terminal"
bun run dev
# or, equivalently
bunx solid-start dev
bun dev
```
---
```txt
$ vinxi dev
vinxi v0.5.8
vinxi starting dev server
➜ Local: http://localhost:3000/
➜ Network: use --host to expose
```
Open [localhost:3000](http://localhost:3000). Any changes you make to `src/routes/index.tsx` will be hot-reloaded automatically.
<Frame>
![SolidStart demo app](https://github.com/oven-sh/bun/assets/3084745/1e8043c4-49d1-498c-9add-c1eaab6c7167)
</Frame>
---
Refer to the [SolidStart website](https://start.solidjs.com/getting-started/what-is-solidstart) for complete framework documentation.
Refer to the [SolidStart website](https://docs.solidjs.com/solid-start) for complete framework documentation.

29
docs/guides/util/detect-bun.mdx
View File

@@ -4,22 +4,25 @@ sidebarTitle: Detect Bun
mode: center
---
The recommended way to conditionally detect when code is being executed with `bun` is to check for the existence of the `Bun` global.
This is similar to how you'd check for the existence of the `window` variable to detect when code is being executed in a browser.
```ts
if (typeof Bun !== "undefined") {
// this code will only run when the file is run with Bun
}
```
---
In TypeScript environments, the previous approach will result in a type error unless `@types/bun` is installed. To avoid this, you can check `process.versions` instead.
The recommended way to detect when code is being executed with Bun is to check `process.versions.bun`. This works in both JavaScript and TypeScript without requiring any additional type definitions.
```ts
if (process.versions.bun) {
// this code will only run when the file is run with Bun
}
```
---
Alternatively, you can check for the existence of the `Bun` global. This is similar to how you'd check for the existence of the `window` variable to detect when code is being executed in a browser.
<Note>
This approach will result in a type error in TypeScript unless `@types/bun` is installed. You can install it with `bun
add -d @types/bun`.
</Note>
```ts
if (typeof Bun !== "undefined") {
// this code will only run when the file is run with Bun
}
```

93
docs/guides/util/upgrade.mdx Normal file
View File

@@ -0,0 +1,93 @@
---
title: Upgrade Bun to the latest version
sidebarTitle: Upgrade Bun
mode: center
---
Bun can upgrade itself using the built-in `bun upgrade` command. This is the fastest way to get the latest features and bug fixes.
```bash terminal icon="terminal"
bun upgrade
```
This downloads and installs the latest stable version of Bun, replacing the currently installed version.
<Note>To see the current version of Bun, run `bun --version`.</Note>
---
## Verify the upgrade
After upgrading, verify the new version:
```bash terminal icon="terminal"
bun --version
# Output: 1.x.y
# See the exact commit of the Bun binary
bun --revision
# Output: 1.x.y+abc123def
```
---
## Upgrade to canary builds
Canary builds are automatically released on every commit to the `main` branch. These are untested but useful for trying new features or verifying bug fixes before they're released.
```bash terminal icon="terminal"
bun upgrade --canary
```
<Warning>Canary builds are not recommended for production use. They may contain bugs or breaking changes.</Warning>
---
## Switch back to stable
If you're on a canary build and want to return to the latest stable release:
```bash terminal icon="terminal"
bun upgrade --stable
```
---
## Install a specific version
To install a specific version of Bun, use the install script with a version tag:
<Tabs>
<Tab title="macOS & Linux">
```bash terminal icon="terminal"
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.3"
```
</Tab>
<Tab title="Windows">
```powershell PowerShell icon="windows"
iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.3.3"
```
</Tab>
</Tabs>
---
## Package manager users
If you installed Bun via a package manager, use that package manager to upgrade instead of `bun upgrade` to avoid conflicts.
<Tip>
**Homebrew users** <br />
To avoid conflicts with Homebrew, use `brew upgrade bun` instead.
**Scoop users** <br />
To avoid conflicts with Scoop, use `scoop update bun` instead.
</Tip>
---
## See also
- [Installation](/installation) — Install Bun for the first time
- [Update packages](/pm/cli/update) — Update dependencies to latest versions

8
docs/pm/bunx.mdx
View File

@@ -3,6 +3,8 @@ title: "bunx"
description: "Run packages from npm"
---
import Bunx from "/snippets/cli/bunx.mdx";
<Note>`bunx` is an alias for `bun x`. The `bunx` CLI will be auto-installed when you install `bun`.</Note>
Use `bunx` to auto-install and run packages from `npm`. It's Bun's equivalent of `npx` or `yarn dlx`.
@@ -52,6 +54,8 @@ To pass additional command-line flags and arguments through to the executable, p
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, even if the executable indicates otherwise. To do so, include the `--bun` flag.
@@ -81,3 +85,7 @@ To force bun to always be used with a script, use a shebang.
```js dist/index.js icon="/icons/javascript.svg"
#!/usr/bin/env bun
```
---
<Bunx />

3
docs/runtime/secrets.mdx
View File

@@ -23,10 +23,11 @@ if (!githubToken) {
name: "github-token",
value: githubToken,
});
console.log("GitHub token stored");
}
const response = await fetch("https://api.github.com/name", {
const response = await fetch("https://api.github.com/user", {
headers: { Authorization: `token ${githubToken}` },
});

35
docs/runtime/sqlite.mdx
View File

@@ -172,10 +172,23 @@ const query = db.query(`select "Hello world" as message`);
```
<Note>
Use the `.prepare()` method to prepare a query _without_ caching it on the `Database` instance.
**What does "cached" mean?**
The caching refers to the **compiled prepared statement** (the SQL bytecode), not the query results. When you call `db.query()` with the same SQL string multiple times, Bun returns the same cached `Statement` object instead of recompiling the SQL.
It is completely safe to reuse a cached statement with different parameter values:
```ts
// compile the prepared statement
const query = db.query("SELECT * FROM users WHERE id = ?");
query.get(1); // ✓ Works
query.get(2); // ✓ Also works - parameters are bound fresh each time
query.get(3); // ✓ Still works
```
Use `.prepare()` instead of `.query()` when you want a fresh `Statement` instance that isn't cached, for example if you're dynamically generating SQL and don't want to fill the cache with one-off queries.
```ts
// compile the prepared statement without caching
const query = db.prepare("SELECT * FROM foo WHERE bar = ?");
```
@@ -190,7 +203,7 @@ SQLite supports [write-ahead log mode](https://www.sqlite.org/wal.html) (WAL) wh
To enable WAL mode, run this pragma query at the beginning of your application:
```ts db.ts icon="/icons/typescript.svg"
db.exec("PRAGMA journal_mode = WAL;");
db.run("PRAGMA journal_mode = WAL;");
```
<Accordion title="What is WAL mode?">
@@ -650,8 +663,8 @@ class Database {
},
);
prepare<ReturnType, Params>(sql: string): Statement<ReturnType, Params>;
query<ReturnType, Params>(sql: string): Statement<ReturnType, Params>;
query<ReturnType, ParamsType>(sql: string): Statement<ReturnType, ParamsType>;
prepare<ReturnType, ParamsType>(sql: string): Statement<ReturnType, ParamsType>;
run(sql: string, params?: SQLQueryBindings): { lastInsertRowid: number; changes: number };
exec = this.run;
@@ -664,14 +677,14 @@ class Database {
close(throwOnError?: boolean): void;
}
class Statement<ReturnType, Params> {
all(params: Params): ReturnType[];
get(params: Params): ReturnType | undefined;
run(params: Params): {
class Statement<ReturnType, ParamsType> {
all(...params: ParamsType[]): ReturnType[];
get(...params: ParamsType[]): ReturnType | null;
run(...params: ParamsType[]): {
lastInsertRowid: number;
changes: number;
};
values(params: Params): unknown[][];
values(...params: ParamsType[]): unknown[][];
finalize(): void; // destroy statement and clean up resources
toString(): string; // serialize to SQL
@@ -682,7 +695,7 @@ class Statement<ReturnType, Params> {
paramsCount: number; // the number of parameters expected by the statement
native: any; // the native object representing the statement
as(Class: new () => ReturnType): this;
as<T>(Class: new (...args: any[]) => T): Statement<T, ParamsType>;
}
type SQLQueryBindings =

49
docs/snippets/cli/bunx.mdx Normal file
View File

@@ -0,0 +1,49 @@
## Usage
```bash
bunx [flags] <package>[@version] [flags and arguments for the package]
```
Execute an npm package executable (CLI), automatically installing into a global shared cache if not installed in `node_modules`.
### Flags
<ParamField path="--bun" type="boolean">
Force the command to run with Bun instead of Node.js, even if the executable contains a Node shebang (`#!/usr/bin/env
node`)
</ParamField>
<ParamField path="-p, --package" type="string">
Specify package to install when binary name differs from package name
</ParamField>
<ParamField path="--no-install" type="boolean">
Skip installation if package is not already installed
</ParamField>
<ParamField path="--verbose" type="boolean">
Enable verbose output during installation
</ParamField>
<ParamField path="--silent" type="boolean">
Suppress output during installation
</ParamField>
### Examples
```bash terminal icon="terminal"
# Run Prisma migrations
bunx prisma migrate
# Format a file with Prettier
bunx prettier foo.js
# Run a specific version of a package
bunx uglify-js@3.14.0 app.js
# Use --package when binary name differs from package name
bunx -p @angular/cli ng new my-app
# Force running with Bun instead of Node.js, even if the executable contains a Node shebang
bunx --bun vite dev foo.js
```