diff options
Diffstat (limited to 'docs/cli/run.md')
| -rw-r--r-- | docs/cli/run.md | 53 |
1 files changed, 40 insertions, 13 deletions
diff --git a/docs/cli/run.md b/docs/cli/run.md index 133f3e1ec..7a5f8e9d2 100644 --- a/docs/cli/run.md +++ b/docs/cli/run.md @@ -1,31 +1,38 @@ The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin). -## Running a file +<!-- ## Speed --> + +<!-- +Performance sensitive APIs like `Buffer`, `fetch`, and `Response` are heavily profiled and optimized. Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. It starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. --> + +## Run a file {% callout %} Compare to `node <file>` {% /callout %} -Bun can execute `.js`, `.jsx`, `.ts`, and `.tsx` files. Every file is transpiled to vanilla JavaScript by Bun's fast native transpiler before being executed. For details on Bun's runtime, refer to the [Bun runtime](/docs/runtime) documentation. +Use `bun run` to execute a source file. -```ts#foo.ts -import { z } from "zod"; - -const schema = z.string() -const result = schema.parse("Billie Eilish"); -console.log(result); +```bash +$ bun run index.js ``` -To run a file in Bun: +Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed. ```bash -$ bun foo.ts -Billie Eilish +$ bun run index.js +$ bun run index.jsx +$ bun run index.ts +$ bun run index.tsx ``` -If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules). +The "naked" `bun` command is equivalent to `bun run`. -## Running a package script +```bash +$ bun index.tsx +``` + +## Run a `package.json` script {% note %} Compare to `npm run <script>` or `yarn <script>` @@ -80,3 +87,23 @@ quickstart scripts: ``` Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself. + +## Environment variables + +Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order: + +1. `.env.local` (first) +2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development` +3. `.env` + +To debug environment variables, run `bun run env` to view a list of resolved environment variables. + +## Performance + +Bun is designed to start fast and run fast. + +Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. It's transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js. + +{% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%} + +<!-- If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules). --> |