# Installing Bun. ## TL;DR. Bun is a fast JavaScript runtime with TypeScript support. It is designed to be a drop-in replacement for Node.js. The Bun CLI has features like a runtime, bundler, test runner, package runner, package manager, and APIs. This post: * Covers Bun's installation, * Includes a quick start guide, * Introduces the package manager, * Describes TypeScript integration for it's APIs, and * Suggests how templates can be built, and used, for custom initialisations. > ***Attribution:*** > > [https://bun.sh/docs](https://bun.sh/docs) ## An Introduction. Bun is fast because it is written in a low-level programming language called Zig. Unlike other runtimes that use Chrome V8, Bun is powered by JavaScriptCore, the same JavaScript engine that is used by Apple Safari. > The purpose of this post is to introduce the Bun JS runtime. Bun 1.0 was released on Friday 8th September 2023 and the CLI includes: * TypeScript support, * A runtime (bun run), * A bundler (bun build), * A test runner (bun test), * A package runner (bunx), * A package manager (bun install), and * A small (but growing) collection of useful APIs. I will touch on each of these topics as per [the official documentation](https://bun.sh/docs). ## The Big Picture. A JavaScript runtime allows JS code to run on the server. The main advantage lies in the reduction of context switching: JavaScript running on the server *and* in the browser means there is ONE programming language involved during development. At least, that was an intent when Node was launched in 2009. The introduction of ECMAScript 2015, colloquially called ES6, introduced new JavaScript features like const, let, arrow functions, and other features. Further developments would threaten jQuery, although it is still a very popular library. Each year, ECMA would issue updated JavaScript standards and each browser vendor would release new features to match. As JavaScript continued to evolve, modern development practices also changed. These transitions were due to new tools and practices that evolved, hand in hand, with the annual ECMA releases. The current range of development tools is wide and varied. Also, it is common to see a new framework, language, library, or runtime *launch each week*. For instance, Bun 1.0 and the Mojo Local Installer were unveiled *on the same day*!! Suffice it to say that software engineering is a continually evolving field. ## Prerequisites. * A Linux-based distro (I use Ubuntu), * A remote 'bun' container on my homelab [as per these instructions](https://solodev.app/1-of-3-setting-up-a-remote-container). * A remote connection from my workstation [as per these instructions](https://solodev.app/2-of-3-setting-up-a-remote-connection). * A hardened 'bun' container on my homelab [as per these instructions](https://solodev.app/3-of-3-hardening-the-remote-container). > NOTE: The purpose of using containers is to isolate any running processes from other containers and the host system. ## Installing Bun. * I connect VS Code to the 'bun' container (which requires the Microsoft '*Remote - SSH*' extension and the '*F1 -> Remote-SSH: Open SSH Host...*' command.) * From the VS Code terminal (use `CTRL + ~` to show/hide the terminal) I install the unzip package: ```javascript sudo apt install unzip -y ``` * I install Bun: ```javascript curl -fsSL https://bun.sh/install | bash ``` * I set the source: ```javascript source $HOME/.bashrc ``` * I check the version: ```javascript bun -v ``` ## Upgrading and Uninstalling Bun. * I can, if needed, upgrade Bun: ```javascript bun upgrade ``` * I can, if needed, uninstall Bun: ```javascript rm -rf ~/.bun ``` ## Quickstart1. * I make a 'quickstart1' directory: ```javascript mkdir quickstart1 ``` * I change to that directory: ```javascript cd quickstart1 ``` * I scaffold a new project (and accept all the defaults): ```javascript bun init -y ``` ## Hello, Bun as a Hot Reload File. * I add the following to 'index.ts' file and save the changes: ```javascript const server = Bun.serve({ port: 3000, fetch(req) { return new Response("Hello, from Bun."); }, }); console.log(`Listening on http://localhost:${server.port} ...`); ``` * I run the 'index.ts' file from the terminal: ```javascript bun --hot run index.ts ``` * I open a browser on my workstation and point it to 192.168.188.52:3000. * I stop the server (CTRL + C). ## Hello, Bun as a Hot Reload Script. * I open the 'package.json' file. * I add the following: ```javascript "scripts": { "start": "bun --hot run index.ts" }, ``` * I run the script from the terminal: ```javascript bun run start ``` * I open a browser on my workstation and point it to 192.168.188.52:3000. * I stop the server (CTRL + C). ## Installing a Package. * I install the 'figlet' package: ```javascript bun add figlet ``` * FOR TYPESCRIPT USERS ONLY: ```javascript bun add -d @types/figlet ``` * I replace the contents of the 'index.ts' file: ```javascript import figlet from "figlet"; const server = Bun.serve({ fetch() { const body = figlet.textSync("Hello, from Figlet Bun!"); return new Response(body); }, port: 3000, }); ``` * I use the 'package.json' script command to run the server. ```javascript bun run start ``` * I open a browser on my workstation and point it to 192.168.188.52:3000. * I stop the server (CTRL + C). ## TypeScript. * I install the TypeScript definitions for the built-in APIs: ```javascript bun add -d bun-types ``` * I add the following to my 'tsconfig.json' file: ```javascript { "compilerOptions": { "types": ["bun-types"], } } ``` > NOTE: I can now reference the `Bun` global in my TypeScript files. * I add the following to the bottom of the 'index.ts' file: ```javascript console.log(`Bun version: ` + Bun.version); ``` * The following 'tsconfig.json' entries are a set of recommended `compilerOptions` for a Bun project: ```javascript { "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 } } ``` > NOTE: If I run `bun init` in a new directory, this `tsconfig.json` will be generated automatically. * I use the 'package.json' script command to run the server. ```javascript bun run start ``` * I open a browser on my workstation and point it to 192.168.188.52:3000. * I stop the server (CTRL + C). ## DOM Types. * If I need to add DOM types to my project, I add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in my project: ```javascript /// /// ``` ## Templates. * In VS Code, I close the 'quickstart1' directory using File > Close Folder \[CTRL + K F\]. * In the VS Code terminal, I make a 'quickstart2' directory in the home (~) directory: ```javascript mkdir quickstart2 ``` * In VS Code, I click the blue 'Open Folder' button, select the 'quickstart2' directory, and click the blue 'OK' button. * I open the VS Code terminal with CTRL + ~. * In the terminal, I change to the 'quickstart2' directory: ```javascript cd quickstart2 ``` * I scaffold an empty project with the interactive `bun init` command (and I use the -y flag to auto-accept the default settings): ```javascript bun init -y ``` * I template a new Bun project with `bun create`: ```javascript bun create