From 6161c201e17cb104436b5fe1f0b6b7b069fbe39d Mon Sep 17 00:00:00 2001 From: Antonin CLAUZIER Date: Wed, 13 Sep 2023 12:38:17 +0400 Subject: Update discordjs.md (#5227) --- docs/guides/ecosystem/discordjs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/discordjs.md b/docs/guides/ecosystem/discordjs.md index 0a70f6f05..ec12a247d 100644 --- a/docs/guides/ecosystem/discordjs.md +++ b/docs/guides/ecosystem/discordjs.md @@ -74,4 +74,4 @@ Ready! Logged in as my-bot#1234 --- -You're up and running with a bare-bones Discord.js bot! This is a basic guide to setting up your bot with Bun; we recommend the [official Discord docs](https://discordjs.guide/) for complete information on the `discord.js` API. +You're up and running with a bare-bones Discord.js bot! This is a basic guide to setting up your bot with Bun; we recommend the [official discord.js docs](https://discordjs.guide/) for complete information on the `discord.js` API. -- cgit v1.2.3 From c99caccdb2e1bb961b13766ec7ebb9907763e364 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Wed, 13 Sep 2023 20:43:39 -0700 Subject: More docs & helptext cleanup (#5229) * wip * Flesh out resolution docs * Polish * More * WIP * WIP * WIP * Document --watch --- docs/api/file-io.md | 2 +- docs/bundler/index.md | 8 ++++ docs/bundler/vs-esbuild.md | 4 +- docs/guides/ecosystem/nextjs.md | 13 ++++++- docs/guides/install/registry-scope.md | 6 ++- docs/guides/install/workspaces.md | 4 +- docs/guides/runtime/typescript.md | 69 +++++++++++++++++++++++++++++++++++ docs/installation.md | 2 + docs/runtime/modules.md | 26 +++++++++++-- src/cli.zig | 17 +++++---- 10 files changed, 133 insertions(+), 18 deletions(-) create mode 100644 docs/guides/runtime/typescript.md (limited to 'docs/guides/ecosystem') diff --git a/docs/api/file-io.md b/docs/api/file-io.md index e6902cc6a..f37473c33 100644 --- a/docs/api/file-io.md +++ b/docs/api/file-io.md @@ -2,7 +2,7 @@ -**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir`, you can use Bun's [nearly complete](/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. +**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir` or `readdir`, you can use Bun's [nearly complete](/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. {% /callout %} diff --git a/docs/bundler/index.md b/docs/bundler/index.md index 585a6ac52..8db531ce5 100644 --- a/docs/bundler/index.md +++ b/docs/bundler/index.md @@ -132,6 +132,14 @@ Visit `http://localhost:5000` to see your bundled app in action. {% /details %} +## Watch mode + +Like the runtime and test runner, the bundler supports watch mode natively. + +```sh +$ bun build ./index.tsx --outdir ./out --watch +``` + ## Content types Like the Bun runtime, the bundler supports an array of file types out of the box. The following table breaks down the bundler's set of standard "loaders". Refer to [Bundler > File types](/docs/runtime/loaders) for full documentation. diff --git a/docs/bundler/vs-esbuild.md b/docs/bundler/vs-esbuild.md index 44ab835a3..67bed3dc3 100644 --- a/docs/bundler/vs-esbuild.md +++ b/docs/bundler/vs-esbuild.md @@ -130,8 +130,8 @@ In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Ot --- - `--watch` -- n/a -- Not applicable +- `--watch` +- No differences --- diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md index a455eb23e..4d3be8cfc 100644 --- a/docs/guides/ecosystem/nextjs.md +++ b/docs/guides/ecosystem/nextjs.md @@ -3,7 +3,7 @@ name: Build an app with Next.js and Bun --- {% callout %} -Next.js 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. +The Next.js [App Router](https://nextjs.org/docs/app) 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. {% /callout %} --- @@ -23,7 +23,16 @@ Creating a new Next.js app in /path/to/my-app. --- -To start the dev server, run `bun run dev` from the project root. +To start the dev server with Bun, run `bun --bun run dev` from the project root. + +```sh +$ cd my-app +$ bun --bun run dev +``` + +--- + +To run the dev server with Node.js instead, omit `--bun`. ```sh $ cd my-app diff --git a/docs/guides/install/registry-scope.md b/docs/guides/install/registry-scope.md index 48f7dee79..68d8cf942 100644 --- a/docs/guides/install/registry-scope.md +++ b/docs/guides/install/registry-scope.md @@ -11,7 +11,11 @@ Bun does not read `.npmrc` files; instead private registries are configured via # as an object with username/password # you can reference environment variables -"@myorg2" = { username = "myusername", password = "$npm_pass", url = "https://registry.myorg.com/" } +"@myorg2" = { + username = "myusername", + password = "$npm_pass", + url = "https://registry.myorg.com/" +} # as an object with token "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" } diff --git a/docs/guides/install/workspaces.md b/docs/guides/install/workspaces.md index f87c1e337..4628d6aaa 100644 --- a/docs/guides/install/workspaces.md +++ b/docs/guides/install/workspaces.md @@ -4,6 +4,8 @@ name: Configuring a monorepo using workspaces Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory. +Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces. + --- The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`. @@ -37,7 +39,7 @@ It's common to place all packages in a `packages` directory. The `"workspaces"` To add one workspace as a dependency of another, modify its `package.json`. Here we're adding `stuff-a` as a dependency of `stuff-b`. -```json#packages/stuff-b/package.json +```json-diff#packages/stuff-b/package.json { "name": "stuff-b", "dependencies": { diff --git a/docs/guides/runtime/typescript.md b/docs/guides/runtime/typescript.md new file mode 100644 index 000000000..f6afe02c1 --- /dev/null +++ b/docs/guides/runtime/typescript.md @@ -0,0 +1,69 @@ +--- +name: Install TypeScript declarations for Bun +--- + +To install TypeScript definitions for Bun's built-in APIs in your project, install `bun-types`. + +```sh +$ bun add -d bun-types # dev dependency +``` + +--- + +Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`: + +```json-diff + { + "compilerOptions": { ++ "types": ["bun-types"] + } + } +``` + +--- + +Unfortunately, setting a value for `"types"` means that TypeScript will ignore other global type definitions, including `lib: ["dom"]`. If you need to add DOM types into your project, add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in your project. + +```ts +/// +/// +``` + +--- + +Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX. + +```jsonc +{ + "compilerOptions": { + // add Bun type definitions + "types": ["bun-types"], + + // enable latest features + "lib": ["esnext"], + "module": "esnext", + "target": "esnext", + + // if TS 5.x+ + "moduleResolution": "bundler", + "noEmit": true, + "allowImportingTsExtensions": true, + "moduleDetection": "force", + // if TS 4.x or earlier + // "moduleResolution": "nodenext", + + "jsx": "react-jsx", // support JSX + "allowJs": true, // allow importing `.js` from `.ts` + "esModuleInterop": true, // allow default imports for CommonJS modules + + // best practices + "strict": true, + "forceConsistentCasingInFileNames": true, + "skipLibCheck": true + } +} +``` + +--- + +Refer to [Ecosystem > TypeScript](/docs/runtime/typescript) for a complete guide to TypeScript support in Bun. diff --git a/docs/installation.md b/docs/installation.md index df4d12cea..c0b823623 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,6 +10,8 @@ Bun ships as a single executable that can be installed a few different ways. ```bash#macOS/Linux_(curl) $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL +# to install a specific version +$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0" ``` ```bash#NPM diff --git a/docs/runtime/modules.md b/docs/runtime/modules.md index a876a5a2b..fe8bb8c64 100644 --- a/docs/runtime/modules.md +++ b/docs/runtime/modules.md @@ -184,18 +184,38 @@ Once it finds the `foo` package, Bun reads the `package.json` to determine how t Whichever one of these conditions occurs _first_ in the `package.json` is used to determine the package's entrypoint. -Bun respects subpath [`"exports"`](https://nodejs.org/api/packages.html#subpath-exports) and [`"imports"`](https://nodejs.org/api/packages.html#imports). Specifying any subpath in the `"exports"` map will prevent other subpaths from being importable. +Bun respects subpath [`"exports"`](https://nodejs.org/api/packages.html#subpath-exports) and [`"imports"`](https://nodejs.org/api/packages.html#imports). ```jsonc#package.json { "name": "foo", "exports": { - ".": "./index.js", - "./package.json": "./package.json" // subpath + ".": "./index.js" } } ``` +Subpath imports and conditional imports work in conjunction with each other. + +``` +{ + "name": "foo", + "exports": { + ".": { + "import": "./index.mjs", + "require": "./index.js" + } + } +} +``` + +As in Node.js, Specifying any subpath in the `"exports"` map will prevent other subpaths from being importable; you can only import files that are explicitly exported. Given the `package.json` above: + +```ts +import stuff from "foo"; // this works +import stuff from "foo/index.mjs"; // this doesn't +``` + {% callout %} **Shipping TypeScript** — Note that Bun supports the special `"bun"` export condition. If your library is written in TypeScript, you can publish your (un-transpiled!) TypeScript files to `npm` directly. If you specify your package's `*.ts` entrypoint in the `"bun"` condition, Bun will directly import and execute your TypeScript source files. {% /callout %} diff --git a/src/cli.zig b/src/cli.zig index 889da9320..6f05bd8cb 100644 --- a/src/cli.zig +++ b/src/cli.zig @@ -75,6 +75,7 @@ pub const Cli = struct { \\ --target The intended execution environment for the bundle. \\ ("browser", "bun" or "node") \\ --splitting Enable code splitting (requires --outdir) + \\ --watch Run bundler in watch mode \\ \\Examples: \\ Frontend web apps: @@ -168,7 +169,7 @@ pub const Arguments = struct { clap.parseParam("-h, --help Display this help and exit.") catch unreachable, clap.parseParam("-b, --bun Force a script or package to use Bun's runtime instead of Node.js (via symlinking node)") catch unreachable, clap.parseParam("--cwd Absolute path to resolve files & entry points from. This just changes the process' cwd.") catch unreachable, - clap.parseParam("-c, --config ? Config file to load bun from (e.g. -c bunfig.toml") catch unreachable, + clap.parseParam("-c, --config ? Config file to load Bun from (e.g. -c bunfig.toml") catch unreachable, clap.parseParam("--extension-order ... Defaults to: .tsx,.ts,.jsx,.js,.json ") catch unreachable, clap.parseParam("--jsx-factory Changes the function called when compiling JSX elements using the classic JSX runtime") catch unreachable, clap.parseParam("--jsx-fragment Changes the function called when compiling JSX fragments") catch unreachable, @@ -184,7 +185,7 @@ pub const Arguments = struct { clap.parseParam("-e, --external ... Exclude module from transpilation (can use * wildcards). ex: -e react") catch unreachable, clap.parseParam("-l, --loader ... Parse files with .ext:loader, e.g. --loader .js:jsx. Valid loaders: js, jsx, ts, tsx, json, toml, text, file, wasm, napi") catch unreachable, clap.parseParam("-u, --origin Rewrite import URLs to start with --origin. Default: \"\"") catch unreachable, - clap.parseParam("-p, --port Port to serve bun's dev server on. Default: \"3000\"") catch unreachable, + clap.parseParam("-p, --port Port to serve Bun's dev server on. Default: \"3000\"") catch unreachable, clap.parseParam("--smol Use less memory, but run garbage collection more often") catch unreachable, clap.parseParam("--minify Minify (experimental)") catch unreachable, clap.parseParam("--minify-syntax Minify syntax and inline data (experimental)") catch unreachable, @@ -201,13 +202,13 @@ pub const Arguments = struct { // note: we are keeping --port and --origin as it can be reused for bun // build and elsewhere pub const not_bun_dev_flags = [_]ParamType{ - clap.parseParam("--hot Enable auto reload in bun's JavaScript runtime") catch unreachable, - clap.parseParam("--watch Automatically restart bun's JavaScript runtime on file change") catch unreachable, - clap.parseParam("--no-install Disable auto install in bun's JavaScript runtime") catch unreachable, - clap.parseParam("-i Automatically install dependencies and use global cache in bun's runtime, equivalent to --install=fallback") catch unreachable, + clap.parseParam("--hot Enable auto reload in the Bun runtime, test runner, or bundler") catch unreachable, + clap.parseParam("--watch Automatically restart the process on file change") catch unreachable, + clap.parseParam("--no-install Disable auto install in the Bun runtime") catch unreachable, + clap.parseParam("-i Automatically install dependencies and use global cache in Bun's runtime, equivalent to --install=fallback") catch unreachable, clap.parseParam("--install Install dependencies automatically when no node_modules are present, default: \"auto\". \"force\" to ignore node_modules, fallback to install any missing") catch unreachable, - clap.parseParam("--prefer-offline Skip staleness checks for packages in bun's JavaScript runtime and resolve from disk") catch unreachable, - clap.parseParam("--prefer-latest Use the latest matching versions of packages in bun's JavaScript runtime, always checking npm") catch unreachable, + clap.parseParam("--prefer-offline Skip staleness checks for packages in the Bun runtime and resolve from disk") catch unreachable, + clap.parseParam("--prefer-latest Use the latest matching versions of packages in the Bun runtime, always checking npm") catch unreachable, clap.parseParam("--silent Don't repeat the command for bun run") catch unreachable, }; -- cgit v1.2.3 From a8cef7ae75ad9f21a5500fd8c1941629eddd5794 Mon Sep 17 00:00:00 2001 From: Madhurjya Roy Date: Thu, 14 Sep 2023 09:15:37 +0530 Subject: doc(guides): update sveltekit guide (#5285) * doc(guides): update sveltekit guide Use `bun create svelte` instead of `bunx create-svelte`. This is to bring the documentation at par with the SvelteKit official doc to [create a project](https://kit.svelte.dev/docs/creating-a-project). * Update text instructions for sveltekit.md --- docs/guides/ecosystem/sveltekit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/sveltekit.md b/docs/guides/ecosystem/sveltekit.md index 172b77299..6386673bc 100644 --- a/docs/guides/ecosystem/sveltekit.md +++ b/docs/guides/ecosystem/sveltekit.md @@ -2,10 +2,10 @@ name: Build an app with SvelteKit and Bun --- -Use `bunx` to scaffold your app with the `create-svelte` CLI. Answer the prompts to select a template and set up your development environment. +Use `bun create` to scaffold your app with the `svelte` package. Answer the prompts to select a template and set up your development environment. ```sh -$ bunx create-svelte my-app +$ bun create svelte@latest my-app ┌ Welcome to SvelteKit! │ ◇ Which Svelte app template? -- cgit v1.2.3 From 6ac70a6dd2449da987462f2cdcdf80c770abadaf Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Wed, 13 Sep 2023 20:47:36 -0700 Subject: Use bun create everywhere --- docs/guides/ecosystem/astro.md | 4 ++-- docs/guides/ecosystem/hono.md | 2 +- docs/guides/ecosystem/nextjs.md | 2 +- docs/guides/ecosystem/remix.md | 2 +- docs/guides/ecosystem/solidstart.md | 2 +- docs/guides/ecosystem/vite.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/astro.md b/docs/guides/ecosystem/astro.md index 6a8a9fa5f..dac2bc369 100644 --- a/docs/guides/ecosystem/astro.md +++ b/docs/guides/ecosystem/astro.md @@ -2,10 +2,10 @@ name: Build an app with Astro and Bun --- -Initialize a fresh Astro app with `bunx create-astro`. The `create-astro` package detects when you are using `bunx` and will automatically install dependencies using `bun`. +Initialize a fresh Astro app with `bun create astro`. The `create-astro` package detects when you are using `bunx` and will automatically install dependencies using `bun`. ```sh -$ bunx create-astro +$ bun create astro ╭─────╮ Houston: │ ◠ ◡ ◠ We're glad to have you on board. ╰─────╯ diff --git a/docs/guides/ecosystem/hono.md b/docs/guides/ecosystem/hono.md index 6d928a655..df662973d 100644 --- a/docs/guides/ecosystem/hono.md +++ b/docs/guides/ecosystem/hono.md @@ -18,7 +18,7 @@ export default app; Use `create-hono` to get started with one of Hono's project templates. Select `bun` when prompted for a template. ```bash -$ bunx create-hono myapp +$ bun create hono myapp ✔ Which template do you want to use? › bun cloned honojs/starter#main to /path/to/myapp ✔ Copied project files diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md index 4d3be8cfc..a3ad8550c 100644 --- a/docs/guides/ecosystem/nextjs.md +++ b/docs/guides/ecosystem/nextjs.md @@ -11,7 +11,7 @@ The Next.js [App Router](https://nextjs.org/docs/app) currently relies on Node.j Initialize a Next.js app with `create-next-app`. This automatically installs dependencies using `npm`. ```sh -$ bunx create-next-app +$ bun create next-app ✔ What is your project named? … my-app ✔ Would you like to use TypeScript with this project? … No / Yes ✔ Would you like to use ESLint with this project? … No / Yes diff --git a/docs/guides/ecosystem/remix.md b/docs/guides/ecosystem/remix.md index ee6185294..56198d603 100644 --- a/docs/guides/ecosystem/remix.md +++ b/docs/guides/ecosystem/remix.md @@ -11,7 +11,7 @@ Remix currently relies on Node.js APIs that Bun does not yet implement. The guid Initialize a Remix app with `create-remix`. ```sh -$ bunx create-remix +$ bun create remix remix v1.19.3 💿 Let's build a better website... diff --git a/docs/guides/ecosystem/solidstart.md b/docs/guides/ecosystem/solidstart.md index ca2ef471e..fb8d54d91 100644 --- a/docs/guides/ecosystem/solidstart.md +++ b/docs/guides/ecosystem/solidstart.md @@ -11,7 +11,7 @@ SolidStart currently relies on Node.js APIs that Bun does not yet implement. The Initialize a SolidStart app with `create-solid`. ```sh -$ bunx create-solid my-app +$ bun create solid my-app create-solid version 0.2.31 Welcome to the SolidStart setup wizard! diff --git a/docs/guides/ecosystem/vite.md b/docs/guides/ecosystem/vite.md index 3cad145f9..03ff85472 100644 --- a/docs/guides/ecosystem/vite.md +++ b/docs/guides/ecosystem/vite.md @@ -11,7 +11,7 @@ While Vite currently works with Bun, it has not been heavily optimized, nor has Vite works out of the box with Bun. Get started with one of Vite's templates. ```bash -$ bunx create-vite my-app +$ bun create vite my-app ✔ Select a framework: › React ✔ Select a variant: › TypeScript + SWC Scaffolding project in /path/to/my-app... -- cgit v1.2.3 From 49a44eef0f3b6ef51ad46392be47e1cfbaf7435b Mon Sep 17 00:00:00 2001 From: kryparnold <45902187+kryparnold@users.noreply.github.com> Date: Thu, 14 Sep 2023 07:59:16 +0300 Subject: Update nextjs.md (#4905) --- docs/guides/ecosystem/nextjs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md index a3ad8550c..d8bf337c2 100644 --- a/docs/guides/ecosystem/nextjs.md +++ b/docs/guides/ecosystem/nextjs.md @@ -41,4 +41,4 @@ $ bun run dev --- -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. Any changes you make to `pages/index.tsx` will be hot-reloaded in the browser. +Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. Any changes you make to `(pages/app)/index.tsx` will be hot-reloaded in the browser. -- cgit v1.2.3 From b31d76b03d392a252b3f7e41c3ffaca127c1809f Mon Sep 17 00:00:00 2001 From: Soheil Nazari <113988347+s0h311@users.noreply.github.com> Date: Thu, 14 Sep 2023 07:00:31 +0200 Subject: Update nuxt.md (#4452) * Update nuxt.md * --bun --------- Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/nuxt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/nuxt.md b/docs/guides/ecosystem/nuxt.md index c86029dc2..ca42c765b 100644 --- a/docs/guides/ecosystem/nuxt.md +++ b/docs/guides/ecosystem/nuxt.md @@ -22,7 +22,7 @@ bun install v1.x (16b4bf34) --- -To start the dev server, run `bun run dev` from the project root. This will execute the `nuxt dev` command (as defined in the `"dev"` script in `package.json`). +To start the dev server, run `bun --bun run dev` from the project root. This will execute the `nuxt dev` command (as defined in the `"dev"` script in `package.json`). {% callout %} The `nuxt` CLI uses Node.js by default; passing the `--bun` flag forces the dev server to use the Bun runtime instead. -- cgit v1.2.3 From 2a6fdc22988bbca30a44fa1f4c763beb20f9a825 Mon Sep 17 00:00:00 2001 From: Quentin <39061148+LapsTimeOFF@users.noreply.github.com> Date: Mon, 18 Sep 2023 03:18:18 +0200 Subject: Fix a `'app.server' is possibly 'null'.` error (#5626) --- docs/guides/ecosystem/elysia.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/elysia.md b/docs/guides/ecosystem/elysia.md index ae1a8e37b..019686a63 100644 --- a/docs/guides/ecosystem/elysia.md +++ b/docs/guides/ecosystem/elysia.md @@ -21,7 +21,7 @@ const app = new Elysia() .get('/', () => 'Hello Elysia') .listen(8080) -console.log(`🦊 Elysia is running at on port ${app.server.port}...`) +console.log(`🦊 Elysia is running at on port ${app.server?.port}...`) ``` --- -- cgit v1.2.3 From d362a8b9ec7f1e5ce7b1aff7573ce4bc44e05565 Mon Sep 17 00:00:00 2001 From: Brooks Lybrand Date: Tue, 19 Sep 2023 14:39:23 -0500 Subject: docs: Update Remix guide (#5702) * Update Remix guide * Update callout * Update docs/guides/ecosystem/remix.md Co-authored-by: Michael Jackson * update * Add link to remix --------- Co-authored-by: Michael Jackson Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/remix.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/remix.md b/docs/guides/ecosystem/remix.md index 56198d603..1aba08b23 100644 --- a/docs/guides/ecosystem/remix.md +++ b/docs/guides/ecosystem/remix.md @@ -3,7 +3,7 @@ name: Build an app with Remix and Bun --- {% callout %} -Remix 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. +Currently the Remix development server (`remix dev`) 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. {% /callout %} --- @@ -58,3 +58,21 @@ $ bun run dev Open [http://localhost:3000](http://localhost:3000) to see the app. Any changes you make to `app/routes/_index.tsx` will be hot-reloaded in the browser. {% image src="https://github.com/oven-sh/bun/assets/3084745/c26f1059-a5d4-4c0b-9a88-d9902472fd77" caption="Remix app running on localhost" /%} + +--- + +To build and start your app, run `bun run build` then `bun run start` from the project root. + +```sh +$ bun run build + $ remix build + info building... (NODE_ENV=production) + info built (158ms) +$ bun start + $ remix-serve ./build/index.js + [remix-serve] http://localhost:3000 (http://192.168.86.237:3000) +``` + +--- + +Read the [Remix docs](https://remix.run/) for more information on how to build apps with Remix. -- cgit v1.2.3 From fc14902f73c643616f51e702e8a0fc2ac0a2ef85 Mon Sep 17 00:00:00 2001 From: Andrey Gurtovoy Date: Tue, 19 Sep 2023 23:25:13 +0300 Subject: Added react installation to react.md (#5620) * Update react.md Added install react part * Updates * Updates --------- Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/react.md | 47 +++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 14 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/react.md b/docs/guides/ecosystem/react.md index b712e210e..f3c16c153 100644 --- a/docs/guides/ecosystem/react.md +++ b/docs/guides/ecosystem/react.md @@ -2,29 +2,48 @@ name: Use React and JSX --- -React just works with Bun. Bun supports `.jsx` and `.tsx` files out of the box. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution. - -```tsx#react.tsx -function Component(props: {message: string}) { - return ( - -

{props.message}

- - ); -} - -console.log(); +React just works with Bun. Bun supports `.jsx` and `.tsx` files out of the box. + +Remember that JSX is just a special syntax for including HTML-like syntax in JavaScript files. It's commonReact uses JSX syntax, as do other React alternatives like [Preact](https://preactjs.com/) and [Solid](https://www.solidjs.com/). Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution. + +--- + +Bun _assumes_ you're using React (unless you [configure it otherwise](/docs/runtime/bunfig#jsx)) so a line like this: + +``` +const element =

Hello, world!

; ``` --- -Bun implements special logging for JSX to make debugging easier. +is internally converted into something like this: + +```ts +// jsxDEV +import { jsx } from "react/jsx-dev-runtime"; + +const element = jsx("h1", { children: "Hello, world!" }); +``` + +--- + +This code requires `react` to run, so make sure you you've installed React. ```bash -$ bun run react.tsx +$ bun install react +``` + +--- + +Bun implements special logging for JSX components to make debugging easier. + +```bash +$ bun run log-my-component.tsx ``` --- +As far as "official support" for React goes, that's it. React is a library like any other, and Bun can run that library. Bun is not a framework, so you should use a framework like [Vite](https://vitejs.dev/) to build an app with server-side rendering and hot reloading in the browser. + Refer to [Runtime > JSX](/docs/runtime/jsx) for complete documentation on configuring JSX. -- cgit v1.2.3 From ee33d5ced49ceaa70a2e73da59351818a0b9fab3 Mon Sep 17 00:00:00 2001 From: Sanyam Kamat <1625114+sanyamkamat@users.noreply.github.com> Date: Wed, 20 Sep 2023 10:24:45 +0530 Subject: docs: add Qwik guide (#4810) --- docs/guides/ecosystem/qwik.md | 107 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/guides/ecosystem/qwik.md (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/qwik.md b/docs/guides/ecosystem/qwik.md new file mode 100644 index 000000000..45d3f9c1a --- /dev/null +++ b/docs/guides/ecosystem/qwik.md @@ -0,0 +1,107 @@ +--- +name: Build an app with Qwik and Bun +--- + +Initialize a new Qwik app with `bunx create-qwik`. + +The `create-qwik` package detects when you are using `bunx` and will automatically install dependencies using `bun`. + +```sh +$ bun create qwik + + ............ + .::: :--------:. + .:::: .:-------:. + .:::::. .:-------. + ::::::. .:------. + ::::::. :-----: + ::::::. .:-----. + :::::::. .-----. + ::::::::.. ---:. + .:::::::::. :-:. + ..:::::::::::: + ...:::: + + +┌ Let's create a Qwik App ✨ (v1.2.10) +│ +◇ Where would you like to create your new project? (Use '.' or './' for current directory) +│ ./my-app +│ +● Creating new project in /path/to/my-app ... 🐇 +│ +◇ Select a starter +│ Basic App +│ +◇ Would you like to install bun dependencies? +│ Yes +│ +◇ Initialize a new git repository? +│ No +│ +◇ Finishing the install. Wanna hear a joke? +│ Yes +│ +○ ────────────────────────────────────────────────────────╮ +│ │ +│ How do you know if there’s an elephant under your bed? │ +│ Your head hits the ceiling! │ +│ │ +├──────────────────────────────────────────────────────────╯ +│ +◇ App Created 🐰 +│ +◇ Installed bun dependencies 📋 +│ +○ Result ─────────────────────────────────────────────╮ +│ │ +│ Success! Project created in my-app directory │ +│ │ +│ Integrations? Add Netlify, Cloudflare, Tailwind... │ +│ bun qwik add │ +│ │ +│ Relevant docs: │ +│ https://qwik.builder.io/docs/getting-started/ │ +│ │ +│ Questions? Start the conversation at: │ +│ https://qwik.builder.io/chat │ +│ https://twitter.com/QwikDev │ +│ │ +│ Presentations, Podcasts and Videos: │ +│ https://qwik.builder.io/media/ │ +│ │ +│ Next steps: │ +│ cd my-app │ +│ bun start │ +│ │ +│ │ +├──────────────────────────────────────────────────────╯ +│ +└ Happy coding! 🎉 + +``` + +--- + +Run `bun run dev` to start the development server. + +```sh +$ bun run dev + $ vite--mode ssr + + VITE v4.4.7 ready in 1190 ms + + ➜ Local: http://localhost:5173/ + ➜ Network: use --host to expose + ➜ press h to show help +``` + +--- + +Open [http://localhost:5173](http://localhost:5173) with your browser to see the result. Qwik will hot-reload your app as you edit your source files. + +{% image src="https://github.com/oven-sh/bun/assets/3084745/ec35f2f7-03dd-4c90-851e-fb4ad150bb28" alt="Qwik screenshot" /%} + +--- + +Refer to the [Qwik docs](https://qwik.builder.io/docs/getting-started/) for complete documentation. -- cgit v1.2.3 From 2e06dbaffe1188caf0a0d2f9b1a4c819369caa53 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Wed, 20 Sep 2023 15:42:03 -0700 Subject: Update prisma guide --- docs/guides/ecosystem/prisma.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/prisma.md b/docs/guides/ecosystem/prisma.md index e697e2133..08d56440d 100644 --- a/docs/guides/ecosystem/prisma.md +++ b/docs/guides/ecosystem/prisma.md @@ -2,6 +2,12 @@ name: Get started using Prisma --- +{% callout %} +**Note** — At the moment Prisma needs Node.js to be installed to run certain generation code. Make sure Node.js is installed in the environment where you're running `bunx prisma` commands. +{% /callout %} + +--- + Prisma works out of the box with Bun. First, create a directory and initialize it with `bun init`. ```bash -- cgit v1.2.3 From 72f9017b21cbb6de83d054a0b985e9fe9a7708f3 Mon Sep 17 00:00:00 2001 From: Moritz Eck Date: Sat, 23 Sep 2023 18:56:37 +0200 Subject: docs: update link to templates in remix guide (#5965) --- docs/guides/ecosystem/remix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/remix.md b/docs/guides/ecosystem/remix.md index 1aba08b23..5adf648ec 100644 --- a/docs/guides/ecosystem/remix.md +++ b/docs/guides/ecosystem/remix.md @@ -18,7 +18,7 @@ $ bun create remix dir Where should we create your new project? ./my-app - ◼ Using basic template See https://remix.run/docs/pages/templates for more + ◼ Using basic template See https://remix.run/docs/en/main/guides/templates#templates for more ✔ Template copied git Initialize a new git repository? -- cgit v1.2.3 From 2a14d9e5c978a798af270dcbdcf96460b8e093ee Mon Sep 17 00:00:00 2001 From: Alba Silvente Fuentes <36744484+Dawntraoz@users.noreply.github.com> Date: Tue, 26 Sep 2023 16:13:59 -0700 Subject: Update astro.md to v3 (#6070) --- docs/guides/ecosystem/astro.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/astro.md b/docs/guides/ecosystem/astro.md index dac2bc369..995b036aa 100644 --- a/docs/guides/ecosystem/astro.md +++ b/docs/guides/ecosystem/astro.md @@ -10,7 +10,7 @@ $ bun create astro │ ◠ ◡ ◠ We're glad to have you on board. ╰─────╯ - astro v2.10.5 Launch sequence initiated. + astro v3.1.4 Launch sequence initiated. dir Where should we create your new project? ./fumbling-field @@ -55,21 +55,17 @@ By default, Bun will run the dev server with Node.js. To use the Bun runtime ins ```sh $ bunx --bun astro dev - 🚀 astro v2.10.5 started in 200ms + 🚀 astro v3.1.4 started in 200ms - ┃ Local http://localhost:3000/ + ┃ Local http://localhost:4321/ ┃ Network use --host to expose - -01:48:34 PM [content] Watching src/content/ for changes -01:48:34 PM [content] Types generated -01:48:34 PM [astro] update /.astro/types.d.ts ``` --- -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. Astro will hot-reload your app as you edit your source files. +Open [http://localhost:4321](http://localhost:4321) with your browser to see the result. Astro will hot-reload your app as you edit your source files. -{% image src="https://github.com/vitejs/vite/assets/3084745/bb1d5063-32f4-4598-b33e-50b44a1c4e8a" caption="An Astro starter app running on Bun" %} +{% image src="https://imgur.com/Dswiu6w" caption="An Astro v3 starter app running on Bun" %} --- -- cgit v1.2.3 From e62fef67658240a4137320729ff26e09498a93fd Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 28 Sep 2023 11:27:08 -0700 Subject: Update prisma guide --- docs/guides/ecosystem/prisma.md | 41 ++++++++++++++++++++++++++++++++--------- src/bun.js/WebKit | 2 +- 2 files changed, 33 insertions(+), 10 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/prisma.md b/docs/guides/ecosystem/prisma.md index 08d56440d..af83a47e4 100644 --- a/docs/guides/ecosystem/prisma.md +++ b/docs/guides/ecosystem/prisma.md @@ -11,17 +11,17 @@ name: Get started using Prisma Prisma works out of the box with Bun. First, create a directory and initialize it with `bun init`. ```bash -mkdir prisma-app -cd prisma-app -bun init +$ mkdir prisma-app +$ cd prisma-app +$ bun init ``` --- -Then add Prisma as a dependency. +Then install the Prisma CLI (`prisma`) and Prisma Client (`@prisma/client`) as dependencies. ```bash -bun add prisma +$ bun add prisma @prisma/client ``` --- @@ -29,7 +29,7 @@ bun add prisma We'll use the Prisma CLI with `bunx` to initialize our schema and migration directory. For simplicity we'll be using an in-memory SQLite database. ```bash -bunx prisma init --datasource-provider sqlite +$ bunx prisma init --datasource-provider sqlite ``` --- @@ -60,14 +60,37 @@ Then generate and run initial migration. This will generate a `.sql` migration file in `prisma/migrations`, create a new SQLite instance, and execute the migration against the new instance. ```bash -bunx prisma migrate dev --name init +$ bunx prisma migrate dev --name init +Environment variables loaded from .env +Prisma schema loaded from prisma/schema.prisma +Datasource "db": SQLite database "dev.db" at "file:./dev.db" + +SQLite database dev.db created at file:./dev.db + +Applying migration `20230928182242_init` + +The following migration(s) have been created and applied from new schema changes: + +migrations/ + └─ 20230928182242_init/ + └─ migration.sql + +Your database is now in sync with your schema. + +✔ Generated Prisma Client (v5.3.1) to ./node_modules/@prisma/client in 41ms ``` --- -Prisma automatically generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. +As indicated in the output, Prisma re-generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. You can manually re-generate the client with the Prisma CLI. + +```sh +$ bunx prisma generate +``` + +--- -It can be imported from `@prisma/client`. +We can import the generated client from `@prisma/client`. ```ts#src/index.ts import {PrismaClient} from "@prisma/client"; diff --git a/src/bun.js/WebKit b/src/bun.js/WebKit index 6ee85cc2d..e1aa0a58e 160000 --- a/src/bun.js/WebKit +++ b/src/bun.js/WebKit @@ -1 +1 @@ -Subproject commit 6ee85cc2dc431e146723885bc73ac14f33e0d82b +Subproject commit e1aa0a58e282b53fc20503d6e7ec93c621bc5570 -- cgit v1.2.3 From 5fedc8bd6c84d26d283e1c6c300191e6ec388112 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 28 Sep 2023 11:31:47 -0700 Subject: Revert "Update prisma guide" This reverts commit e62fef67658240a4137320729ff26e09498a93fd. --- docs/guides/ecosystem/prisma.md | 41 +++++++++-------------------------------- src/bun.js/WebKit | 2 +- 2 files changed, 10 insertions(+), 33 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/prisma.md b/docs/guides/ecosystem/prisma.md index af83a47e4..08d56440d 100644 --- a/docs/guides/ecosystem/prisma.md +++ b/docs/guides/ecosystem/prisma.md @@ -11,17 +11,17 @@ name: Get started using Prisma Prisma works out of the box with Bun. First, create a directory and initialize it with `bun init`. ```bash -$ mkdir prisma-app -$ cd prisma-app -$ bun init +mkdir prisma-app +cd prisma-app +bun init ``` --- -Then install the Prisma CLI (`prisma`) and Prisma Client (`@prisma/client`) as dependencies. +Then add Prisma as a dependency. ```bash -$ bun add prisma @prisma/client +bun add prisma ``` --- @@ -29,7 +29,7 @@ $ bun add prisma @prisma/client We'll use the Prisma CLI with `bunx` to initialize our schema and migration directory. For simplicity we'll be using an in-memory SQLite database. ```bash -$ bunx prisma init --datasource-provider sqlite +bunx prisma init --datasource-provider sqlite ``` --- @@ -60,37 +60,14 @@ Then generate and run initial migration. This will generate a `.sql` migration file in `prisma/migrations`, create a new SQLite instance, and execute the migration against the new instance. ```bash -$ bunx prisma migrate dev --name init -Environment variables loaded from .env -Prisma schema loaded from prisma/schema.prisma -Datasource "db": SQLite database "dev.db" at "file:./dev.db" - -SQLite database dev.db created at file:./dev.db - -Applying migration `20230928182242_init` - -The following migration(s) have been created and applied from new schema changes: - -migrations/ - └─ 20230928182242_init/ - └─ migration.sql - -Your database is now in sync with your schema. - -✔ Generated Prisma Client (v5.3.1) to ./node_modules/@prisma/client in 41ms +bunx prisma migrate dev --name init ``` --- -As indicated in the output, Prisma re-generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. You can manually re-generate the client with the Prisma CLI. - -```sh -$ bunx prisma generate -``` - ---- +Prisma automatically generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. -We can import the generated client from `@prisma/client`. +It can be imported from `@prisma/client`. ```ts#src/index.ts import {PrismaClient} from "@prisma/client"; diff --git a/src/bun.js/WebKit b/src/bun.js/WebKit index e1aa0a58e..6ee85cc2d 160000 --- a/src/bun.js/WebKit +++ b/src/bun.js/WebKit @@ -1 +1 @@ -Subproject commit e1aa0a58e282b53fc20503d6e7ec93c621bc5570 +Subproject commit 6ee85cc2dc431e146723885bc73ac14f33e0d82b -- cgit v1.2.3 From 26794680dd2b99c7d311bf92528c1f8b9f1ac087 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 28 Sep 2023 11:32:46 -0700 Subject: Update prisma --- docs/guides/ecosystem/prisma.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/prisma.md b/docs/guides/ecosystem/prisma.md index 08d56440d..af83a47e4 100644 --- a/docs/guides/ecosystem/prisma.md +++ b/docs/guides/ecosystem/prisma.md @@ -11,17 +11,17 @@ name: Get started using Prisma Prisma works out of the box with Bun. First, create a directory and initialize it with `bun init`. ```bash -mkdir prisma-app -cd prisma-app -bun init +$ mkdir prisma-app +$ cd prisma-app +$ bun init ``` --- -Then add Prisma as a dependency. +Then install the Prisma CLI (`prisma`) and Prisma Client (`@prisma/client`) as dependencies. ```bash -bun add prisma +$ bun add prisma @prisma/client ``` --- @@ -29,7 +29,7 @@ bun add prisma We'll use the Prisma CLI with `bunx` to initialize our schema and migration directory. For simplicity we'll be using an in-memory SQLite database. ```bash -bunx prisma init --datasource-provider sqlite +$ bunx prisma init --datasource-provider sqlite ``` --- @@ -60,14 +60,37 @@ Then generate and run initial migration. This will generate a `.sql` migration file in `prisma/migrations`, create a new SQLite instance, and execute the migration against the new instance. ```bash -bunx prisma migrate dev --name init +$ bunx prisma migrate dev --name init +Environment variables loaded from .env +Prisma schema loaded from prisma/schema.prisma +Datasource "db": SQLite database "dev.db" at "file:./dev.db" + +SQLite database dev.db created at file:./dev.db + +Applying migration `20230928182242_init` + +The following migration(s) have been created and applied from new schema changes: + +migrations/ + └─ 20230928182242_init/ + └─ migration.sql + +Your database is now in sync with your schema. + +✔ Generated Prisma Client (v5.3.1) to ./node_modules/@prisma/client in 41ms ``` --- -Prisma automatically generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. +As indicated in the output, Prisma re-generates our _Prisma client_ whenever we execute a new migration. The client provides a fully typed API for reading and writing from our database. You can manually re-generate the client with the Prisma CLI. + +```sh +$ bunx prisma generate +``` + +--- -It can be imported from `@prisma/client`. +We can import the generated client from `@prisma/client`. ```ts#src/index.ts import {PrismaClient} from "@prisma/client"; -- cgit v1.2.3 From 16be721d8a8b9872378e1604b4d80db4a30f9938 Mon Sep 17 00:00:00 2001 From: Alba Silvente Fuentes <36744484+Dawntraoz@users.noreply.github.com> Date: Thu, 28 Sep 2023 12:52:00 -0700 Subject: docs: update image astro.md (#6149) --- docs/guides/ecosystem/astro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/astro.md b/docs/guides/ecosystem/astro.md index 995b036aa..04be12012 100644 --- a/docs/guides/ecosystem/astro.md +++ b/docs/guides/ecosystem/astro.md @@ -65,7 +65,7 @@ $ bunx --bun astro dev Open [http://localhost:4321](http://localhost:4321) with your browser to see the result. Astro will hot-reload your app as you edit your source files. -{% image src="https://imgur.com/Dswiu6w" caption="An Astro v3 starter app running on Bun" %} +{% image src="https://i.imgur.com/Dswiu6w.png" caption="An Astro v3 starter app running on Bun" %} --- -- cgit v1.2.3 From 5f09a4dd0afaf5546780858bbfe98d30c6f9faa7 Mon Sep 17 00:00:00 2001 From: Clément P Date: Wed, 11 Oct 2023 00:36:28 +0200 Subject: Update vite.md (#6399) remove outdated information --- docs/guides/ecosystem/vite.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/vite.md b/docs/guides/ecosystem/vite.md index 03ff85472..cf77e7249 100644 --- a/docs/guides/ecosystem/vite.md +++ b/docs/guides/ecosystem/vite.md @@ -30,8 +30,7 @@ bun install Start the development server with the `vite` CLI using `bunx`. -The `--bun` flag tells Bun to run Vite's CLI using `bun` instead of `node`; by default Bun respects Vite's `#!/usr/bin/env node` [shebang line](). After Bun 1.0 this flag will no longer be necessary. - +The `--bun` flag tells Bun to run Vite's CLI using `bun` instead of `node`; by default Bun respects Vite's `#!/usr/bin/env node` [shebang line](). ```bash bunx --bun vite ``` -- cgit v1.2.3 From 4531cf18c223bd506a2c16d11fc3fd9fa6df6178 Mon Sep 17 00:00:00 2001 From: h2210316651 <46309500+h2210316651@users.noreply.github.com> Date: Thu, 12 Oct 2023 02:52:43 +0530 Subject: Docs : Added instructions to run bun apps in daemon (PM2) to address … (#5931) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Docs : Added instructions to run bun apps in daemon (PM2) to address issue #4734 Added instructions to set bun as pm2 interpreter to extend same functionality as node.js apps. * Add pm2 guide * Add pm2 file --------- Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/pm2.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/guides/ecosystem/pm2.md (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/pm2.md b/docs/guides/ecosystem/pm2.md new file mode 100644 index 000000000..c775c8ca3 --- /dev/null +++ b/docs/guides/ecosystem/pm2.md @@ -0,0 +1,54 @@ +--- +name: Run Bun as a daemon with PM2 +--- + +[PM2](https://pm2.keymetrics.io/) is a popular process manager that manages and runs your applications as daemons (background processes). + +It offers features like process monitoring, automatic restarts, and easy scaling. Using a process manager is common when deploying a Bun application on a cloud-hosted virtual private server (VPS), as it: + +- Keeps your Node.js application running continuously. +- Ensure high availability and reliability of your application. +- Monitor and manage multiple processes with ease. +- Simplify the deployment process. + +--- + +You can use PM2 with Bun in two ways: as a CLI option or in a configuration file. + +### With `--interpreter` + +--- + +To start your application with PM2 and Bun as the interpreter, open your terminal and run the following command: + +```bash +pm2 start --interpreter ~/.bun/bin/bun index.ts +``` + +--- + +### With a configuration file + +--- + +Alternatively, you can create a PM2 configuration file. Create a file named `pm2.config.js` in your project directory and add the following content. + +```javascript +module.exports = { + name: "app", // Name of your application + script: "index.ts", // Entry point of your application + interpreter: "~/.bun/bin/bun", // Path to the Bun interpreter +}; +``` + +--- + +After saving the file, you can start your application with PM2 + +```bash +pm2 start pm2.config.js +``` + +--- + +That’s it! Your JavaScript/TypeScript web server is now running as a daemon with PM2 using Bun as the interpreter. -- cgit v1.2.3 From 079476729106b246b9d7e4aa14257c58d99901d3 Mon Sep 17 00:00:00 2001 From: Nicolae-Rares Ailincai Date: Fri, 13 Oct 2023 21:14:57 +0300 Subject: Adds systemd guide to run a bun application as a daemon (#6451) * systemd-guide * remove-root-from-example * add-more-description * Updates * Updates * Updates * Update --------- Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/systemd.md | 113 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/guides/ecosystem/systemd.md (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/systemd.md b/docs/guides/ecosystem/systemd.md new file mode 100644 index 000000000..c22fc9ae2 --- /dev/null +++ b/docs/guides/ecosystem/systemd.md @@ -0,0 +1,113 @@ +--- +name: Run Bun as a daemon with systemd +--- + +[systemd](https://systemd.io) is an init system and service manager for Linux operating systems that manages the startup and control of system processes and services. + + + + + +--- + +To run a Bun application as a daemon using **systemd** you'll need to create a _service file_ in `/lib/systemd/system/`. + +```sh +$ cd /lib/systemd/system +$ touch my-app.service +``` + +--- + +Here is a typical service file that runs an application on system start. You can use this as a template for your own service. Replace `YOUR_USER` with the name of the user you want to run the application as. To run as `root`, replace `YOUR_USER` with `root`, though this is generally not recommended for security reasons. + +Refer to the [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html) for more information on each setting. + +```ini#my-app.service +[Unit] +# describe the app +Description=My App +# start the app after the network is available +After=network.target + +[Service] +# usually you'll use 'simple' +# one of https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type= +Type=simple +# which user to use when starting the app +User=YOUR_USER +# path to your application's root directory +WorkingDirectory=/home/YOUR_USER/path/to/my-app +# the command to start the app +# requires absolute paths +ExecStart=/home/YOUR_USER/.bun/bin/bun run index.ts +# restart policy +# one of {no|on-success|on-failure|on-abnormal|on-watchdog|on-abort|always} +Restart=always + +[Install] +# start the app automatically +WantedBy=multi-user.target +``` + +--- + +If your application starts a webserver, note that non-`root` users are not able to listen on ports 80 or 443 by default. To permanently allow Bun to listen on these ports when executed by a non-`root` user, use the following command. This step isn't necessary when running as `root`. + +```bash +$ sudo setcap CAP_NET_BIND_SERVICE=+eip ~/.bun/bin/bun +``` + +--- + +With the service file configured, you can now _enable_ the service. Once enabled, it will start automatically on reboot. This requires `sudo` permissions. + +```bash +$ sudo systemctl enable my-app +``` + +--- + +To start the service without rebooting, you can manually _start_ it. + +```bash +$ sudo systemctl start my-app +``` + +--- + +Check the status of your application with `systemctl status`. If you've started your app successfully, you should see something like this: + +```bash +$ sudo systemctl status my-app +● my-app.service - My App + Loaded: loaded (/lib/systemd/system/my-app.service; enabled; preset: enabled) + Active: active (running) since Thu 2023-10-12 11:34:08 UTC; 1h 8min ago + Main PID: 309641 (bun) + Tasks: 3 (limit: 503) + Memory: 40.9M + CPU: 1.093s + CGroup: /system.slice/my-app.service + └─309641 /home/YOUR_USER/.bun/bin/bun run /home/YOUR_USER/application/index.ts +``` + +--- + +To update the service, edit the contents of the service file, then reload the daemon. + +```bash +$ sudo systemctl daemon-reload +``` + +--- + +For a complete guide on the service unit configuration, you can check [this page](https://www.freedesktop.org/software/systemd/man/systemd.service.html). Or refer to this cheatsheet of common commands: + +```bash +$ sudo systemctl daemon-reload # tell systemd that some files got changed +$ sudo systemctl enable my-app # enable the app (to allow auto-start) +$ sudo systemctl disable my-app # disable the app (turns off auto-start) +$ sudo systemctl start my-app # start the app if is stopped +$ sudo systemctl stop my-app # stop the app +$ sudo systemctl restart my-app # restart the app +``` -- cgit v1.2.3 From 21576589c63fdc285b785a78a910960d4888a027 Mon Sep 17 00:00:00 2001 From: Nicolae-Rares Ailincai Date: Sat, 14 Oct 2023 04:03:32 +0300 Subject: Guide to containerize a bun application using Docker (#6478) * docker.md * use-debian * Updates --------- Co-authored-by: Colin McDonnell --- docs/guides/ecosystem/docker.md | 140 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/guides/ecosystem/docker.md (limited to 'docs/guides/ecosystem') diff --git a/docs/guides/ecosystem/docker.md b/docs/guides/ecosystem/docker.md new file mode 100644 index 000000000..26a1eaccd --- /dev/null +++ b/docs/guides/ecosystem/docker.md @@ -0,0 +1,140 @@ +--- +name: Containerize a Bun application with Docker +--- + +{% callout %} +This guide assumes you already have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed. +{% /callout %} + +[Docker](https://www.docker.com) is a platform for packaging and running an application as a lightweight, portable _container_ that encapsulates all the necessary dependencies. + +--- + +To _containerize_ our application, we define a `Dockerfile`. This file contains a list of instructions to initialize the container, copy our local project files into it, install dependencies, and starts the application. + +```docker#Dockerfile +# use the official Bun image +# see all versions at https://hub.docker.com/r/oven/bun/tags +FROM oven/bun:1 as base +WORKDIR /usr/src/app + +# install dependencies into temp directory +# this will cache them and speed up future builds +FROM base AS install +RUN mkdir -p /temp/dev +COPY package.json bun.lockb /temp/dev/ +RUN cd /temp/dev && bun install --frozen-lockfile + +# install with --production (exclude devDependencies) +RUN mkdir -p /temp/prod +COPY package.json bun.lockb /temp/prod/ +RUN cd /temp/prod && bun install --frozen-lockfile --production + +# copy node_modules from temp directory +# then copy all (non-ignored) project files into the image +FROM install AS prerelease +COPY --from=install /temp/dev/node_modules node_modules +COPY . . + +# [optional] tests & build +ENV NODE_ENV=production +RUN bun test +RUN bun run build + +# copy production dependencies and source code into final image +FROM base AS release +COPY --from=install /temp/prod/node_modules node_modules +COPY --from=prerelease /usr/src/app/index.ts . +COPY --from=prerelease /usr/src/app/package.json . + +# run the app +USER bun +EXPOSE 3000/tcp +ENTRYPOINT [ "bun", "run", "index.ts" ] +``` + +--- + +Now that you have your docker image, let's look at `.dockerignore` which has the same syntax as `.gitignore`, here you need to specify the files/directories that must not go in any stage of the docker build. An example for a ignore file is + +```txt#.dockerignore +node_modules +Dockerfile* +docker-compose* +.dockerignore +.git +.gitignore +README.md +LICENSE +.vscode +Makefile +helm-charts +.env +.editorconfig +.idea +coverage* +``` + +--- + +We'll now use `docker build` to convert this `Dockerfile` into a _Docker image_, is a self-contained template containing all the dependencies and configuration required to run the application. + +The `-t` flag lets us specify a name for the image, and `--pull` tells Docker to automatically download the latest version of the base image (`oven/bun`). The initial build will take longer, as Docker will download all the base images and dependencies. + +```bash +$ docker build --pull -t bun-hello-world . +[+] Building 0.9s (21/21) FINISHED + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 37B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 35B 0.0s + => [internal] load metadata for docker.io/oven/bun:1 0.8s + => [auth] oven/bun:pull token for registry-1.docker.io 0.0s + => [base 1/2] FROM docker.io/oven/bun:1@sha256:373265748d3cd3624cb3f3ee6004f45b1fc3edbd07a622aeeec17566d2756997 0.0s + => [internal] load build context 0.0s + => => transferring context: 155B 0.0s + # ...lots of commands... + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:360663f7fdcd6f11e8e94761d5592e2e4dfc8d167f034f15cd5a863d5dc093c4 0.0s + => => naming to docker.io/library/bun-hello-world 0.0s +``` + +--- + +We've built a new _Docker image_. Now let's use that image to spin up an actual, running _container_. + +We'll use `docker run` to start a new container using the `bun-hello-world` image. It will be run in _detached_ mode (`-d`) and we'll map the container's port 3000 to our local machine's port 3000 (`-p 3000:3000`). + +The `run` command prints a string representing the _container ID_. + +```sh +$ docker run -d -p 3000:3000 bun-hello-world +7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d +``` + +--- + +The container is now running in the background. Visit [localhost:3000](http://localhost:3000). You should see a `Hello, World!` message. + +--- + +To stop the container, we'll use `docker stop `. + +```sh +$ docker stop 7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d +``` + +--- + +If you can't find the container ID, you can use `docker ps` to list all running containers. + +```sh +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +7f03e212a15e bun-hello-world "bun run index.ts" 2 minutes ago Up 2 minutes 0.0.0.0:3000->3000/tcp flamboyant_cerf +``` + +--- + +That's it! Refer to the [Docker documentation](https://docs.docker.com/) for more advanced usage. -- cgit v1.2.3