Docs: Minor fixes and improvements (#25284)

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

docs/docs.json

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

docs/guides/ecosystem/nuxt.mdx

@@ -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.

docs/guides/ecosystem/solidstart.mdx

@@ -4,63 +4,59 @@ sidebarTitle: "SolidStart with Bun"
 mode: center
 ---
 
-<Warning>
+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.
-  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`.
 
 ```sh terminal icon="terminal"
-bun create solid my-app
+bun create solid my-app --solidstart --ts
 ```
 
 ```txt
-create-solid version 0.2.31
+┌
-
+ Create-Solid v0.6.11
-Welcome to the SolidStart setup wizard!
+│
-
+◇  Project Name
-There are definitely bugs and some feature might not work yet.
+│  my-app
-If you encounter an issue, have a look at
+│
-https://github.com/solidjs/solid-start/issues and open a new one,
+◇  Which template would you like to use?
-if it is not already tracked.
+│  basic
-
+│
-✔ Which template do you want to use? › todomvc
+◇  Project created 🎉
-✔ Server Side Rendering? … yes
+│
-✔ Use TypeScript? … yes
+◇  To get started, run: ─╮
-cloned solidjs/solid-start#main to /path/to/my-app/.solid-start
+│                        │
-✔ Copied project files
+│  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 with `bun dev`.
-
-Then run the development server.
 
 ```sh terminal icon="terminal"
-bun run dev
+bun dev
-# or, equivalently
-bunx solid-start 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.

docs/guides/util/detect-bun.mdx

@@ -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.
+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.
-
-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.
 
 ```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
+}
+```

docs/guides/util/upgrade.mdx

@@ -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

docs/pm/bunx.mdx

@@ -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 />

docs/runtime/secrets.mdx

@@ -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}` },
 });
 

docs/runtime/sqlite.mdx

@@ -172,12 +172,25 @@ 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?**
 
-    ```ts
+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.
-    // compile the prepared statement
+
-    const query = db.prepare("SELECT * FROM foo WHERE bar = ?");
+It is completely safe to reuse a cached statement with different parameter values:
-    ```
+
+```ts
+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 = ?");
+```
 
 </Note>
 
@@ -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, ParamsType>(sql: string): Statement<ReturnType, ParamsType>;
-  query<ReturnType, Params>(sql: string): Statement<ReturnType, Params>;
+  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> {
+class Statement<ReturnType, ParamsType> {
-  all(params: Params): ReturnType[];
+  all(...params: ParamsType[]): ReturnType[];
-  get(params: Params): ReturnType | undefined;
+  get(...params: ParamsType[]): ReturnType | null;
-  run(params: Params): {
+  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 =

docs/snippets/cli/bunx.mdx

@@ -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
+```