diff --git a/docs/docs.json b/docs/docs.json index 4bec7db641..8e5ed5c538 100644 --- a/docs/docs.json +++ b/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", diff --git a/docs/guides/ecosystem/nuxt.mdx b/docs/guides/ecosystem/nuxt.mdx index cf7032f460..2588026116 100644 --- a/docs/guides/ecosystem/nuxt.mdx +++ b/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 +``` + 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. diff --git a/docs/guides/ecosystem/solidstart.mdx b/docs/guides/ecosystem/solidstart.mdx index b958187817..3f742389c8 100644 --- a/docs/guides/ecosystem/solidstart.mdx +++ b/docs/guides/ecosystem/solidstart.mdx @@ -4,63 +4,59 @@ sidebarTitle: "SolidStart with Bun" mode: center --- - - 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. - - ---- - -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. - - ![SolidStart demo app](https://github.com/oven-sh/bun/assets/3084745/1e8043c4-49d1-498c-9add-c1eaab6c7167) - - --- -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. diff --git a/docs/guides/util/detect-bun.mdx b/docs/guides/util/detect-bun.mdx index 0f376749eb..730249c1ca 100644 --- a/docs/guides/util/detect-bun.mdx +++ b/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. - -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. + + + 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`. + + +```ts +if (typeof Bun !== "undefined") { + // this code will only run when the file is run with Bun +} +``` diff --git a/docs/guides/util/upgrade.mdx b/docs/guides/util/upgrade.mdx new file mode 100644 index 0000000000..dea2faacd1 --- /dev/null +++ b/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. + +To see the current version of Bun, run `bun --version`. + +--- + +## 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 +``` + +Canary builds are not recommended for production use. They may contain bugs or breaking changes. + +--- + +## 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: + + + + ```bash terminal icon="terminal" + curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.3" + ``` + + + ```powershell PowerShell icon="windows" + iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.3.3" + ``` + + + +--- + +## Package manager users + +If you installed Bun via a package manager, use that package manager to upgrade instead of `bun upgrade` to avoid conflicts. + + +**Homebrew users**
+To avoid conflicts with Homebrew, use `brew upgrade bun` instead. + +**Scoop users**
+To avoid conflicts with Scoop, use `scoop update bun` instead. + + + +--- + +## See also + +- [Installation](/installation) — Install Bun for the first time +- [Update packages](/pm/cli/update) — Update dependencies to latest versions diff --git a/docs/pm/bunx.mdx b/docs/pm/bunx.mdx index 48dafc0e73..b92ef339ad 100644 --- a/docs/pm/bunx.mdx +++ b/docs/pm/bunx.mdx @@ -3,6 +3,8 @@ title: "bunx" description: "Run packages from npm" --- +import Bunx from "/snippets/cli/bunx.mdx"; + `bunx` is an alias for `bun x`. The `bunx` CLI will be auto-installed when you install `bun`. 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 ``` + +--- + + diff --git a/docs/runtime/secrets.mdx b/docs/runtime/secrets.mdx index 5b49bb2e80..397e7f1c05 100644 --- a/docs/runtime/secrets.mdx +++ b/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}` }, }); diff --git a/docs/runtime/sqlite.mdx b/docs/runtime/sqlite.mdx index 6a6076674a..e09e2046aa 100644 --- a/docs/runtime/sqlite.mdx +++ b/docs/runtime/sqlite.mdx @@ -172,12 +172,25 @@ const query = db.query(`select "Hello world" as message`); ``` - Use the `.prepare()` method to prepare a query _without_ caching it on the `Database` instance. +**What does "cached" mean?** - ```ts - // compile the prepared statement - const query = db.prepare("SELECT * FROM foo WHERE bar = ?"); - ``` +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 +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;"); ``` @@ -650,8 +663,8 @@ class Database { }, ); - prepare(sql: string): Statement; - query(sql: string): Statement; + query(sql: string): Statement; + prepare(sql: string): Statement; run(sql: string, params?: SQLQueryBindings): { lastInsertRowid: number; changes: number }; exec = this.run; @@ -664,14 +677,14 @@ class Database { close(throwOnError?: boolean): void; } -class Statement { - all(params: Params): ReturnType[]; - get(params: Params): ReturnType | undefined; - run(params: Params): { +class Statement { + 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 { paramsCount: number; // the number of parameters expected by the statement native: any; // the native object representing the statement - as(Class: new () => ReturnType): this; + as(Class: new (...args: any[]) => T): Statement; } type SQLQueryBindings = diff --git a/docs/snippets/cli/bunx.mdx b/docs/snippets/cli/bunx.mdx new file mode 100644 index 0000000000..d8de17ece8 --- /dev/null +++ b/docs/snippets/cli/bunx.mdx @@ -0,0 +1,49 @@ +## Usage + +```bash +bunx [flags] [@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 + + + Force the command to run with Bun instead of Node.js, even if the executable contains a Node shebang (`#!/usr/bin/env + node`) + + + + Specify package to install when binary name differs from package name + + + + Skip installation if package is not already installed + + + + Enable verbose output during installation + + + + Suppress output during installation + + +### 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 +```