diff options
Diffstat (limited to 'docs/guides/ecosystem')
-rw-r--r-- | docs/guides/ecosystem/astro.md | 18 | ||||
-rw-r--r-- | docs/guides/ecosystem/discordjs.md | 2 | ||||
-rw-r--r-- | docs/guides/ecosystem/docker.md | 140 | ||||
-rw-r--r-- | docs/guides/ecosystem/elysia.md | 2 | ||||
-rw-r--r-- | docs/guides/ecosystem/hono.md | 2 | ||||
-rw-r--r-- | docs/guides/ecosystem/nextjs.md | 17 | ||||
-rw-r--r-- | docs/guides/ecosystem/nuxt.md | 2 | ||||
-rw-r--r-- | docs/guides/ecosystem/pm2.md | 54 | ||||
-rw-r--r-- | docs/guides/ecosystem/prisma.md | 47 | ||||
-rw-r--r-- | docs/guides/ecosystem/qwik.md | 107 | ||||
-rw-r--r-- | docs/guides/ecosystem/react.md | 47 | ||||
-rw-r--r-- | docs/guides/ecosystem/remix.md | 24 | ||||
-rw-r--r-- | docs/guides/ecosystem/solidstart.md | 2 | ||||
-rw-r--r-- | docs/guides/ecosystem/sveltekit.md | 4 | ||||
-rw-r--r-- | docs/guides/ecosystem/systemd.md | 113 | ||||
-rw-r--r-- | docs/guides/ecosystem/vite.md | 5 |
16 files changed, 535 insertions, 51 deletions
diff --git a/docs/guides/ecosystem/astro.md b/docs/guides/ecosystem/astro.md index 6a8a9fa5f..04be12012 100644 --- a/docs/guides/ecosystem/astro.md +++ b/docs/guides/ecosystem/astro.md @@ -2,15 +2,15 @@ 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. ╰─────╯ - 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://i.imgur.com/Dswiu6w.png" caption="An Astro v3 starter app running on Bun" %} --- 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. 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 <container-id>`. + +```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. 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}...`) ``` --- 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 a455eb23e..d8bf337c2 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 %} --- @@ -11,7 +11,7 @@ Next.js currently relies on Node.js APIs that Bun does not yet implement. The gu 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 @@ -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 @@ -32,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. 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. 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. diff --git a/docs/guides/ecosystem/prisma.md b/docs/guides/ecosystem/prisma.md index e697e2133..af83a47e4 100644 --- a/docs/guides/ecosystem/prisma.md +++ b/docs/guides/ecosystem/prisma.md @@ -2,20 +2,26 @@ 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 -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 ``` --- @@ -23,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 ``` --- @@ -54,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/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. 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 ( - <body> - <h1 style={{color: 'red'}}>{props.message}</h1> - </body> - ); -} - -console.log(<Component message="Hello world!" />); +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 = <h1>Hello, world!</h1>; ``` --- -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 <Component message="Hello world!" /> ``` --- +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. diff --git a/docs/guides/ecosystem/remix.md b/docs/guides/ecosystem/remix.md index ee6185294..5adf648ec 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 %} --- @@ -11,14 +11,14 @@ 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... 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? @@ -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. 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/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? 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. + +<!-- systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and auto mount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit. --> + +<!-- Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution. --> + +--- + +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 +``` diff --git a/docs/guides/ecosystem/vite.md b/docs/guides/ecosystem/vite.md index 3cad145f9..cf77e7249 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... @@ -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](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). 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](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). ```bash bunx --bun vite ``` |