Skip to main content

Beginner Guide - Getting Started with Bun

1. Introduction to Bun​

Bun is a modern, fast, and efficient JavaScript runtime that combines the functionality of Node.js, npm, and a bundler into a single tool. Its speed and simplicity make it a great choice for developers looking to optimize their JavaScript workflows.

Why Use Bun?​

  • Performance: Faster runtime compared to Node.js.
  • All-in-One: Built-in support for running, testing, and bundling JavaScript.
  • Simplified Tooling: Reduces the need for separate tools like npm and Webpack.

2. Prerequisites​

Before getting started with Bun, ensure you have:

  1. A Modern Operating System:

    • Bun supports macOS, Linux, and Windows (via WSL).

  2. Development Tools:

    • Install a terminal or command-line interface (CLI) tool like Bash, Zsh, or PowerShell.

  3. System Requirements:

    • Modern hardware with sufficient CPU and RAM for development tasks.

3. Installing Bun​

Step 1: Install Bun via Script​

Run the following command in your terminal:

curl -fsSL https://bun.sh/install | bash

This command installs Bun and adds it to your PATH.

Step 2: Verify Installation​

Check if Bun is installed correctly:

bun --version

If you see a version number, Bun is ready to use.

Step 3 (Optional): Update Bun​

Keep Bun up to date with:

bun upgrade

4. Creating Your First Project with Bun​

Step 1: Initialize a Project​

Bun simplifies project setup with its fast package manager:

bun init

This command creates a package.json file and sets up your project structure.

Step 2: Install Dependencies​

Install dependencies with:

bun add <package-name>

For example:

bun add react react-dom

Step 3: Run a Script​

Use Bun to execute your scripts:

bun run <script-name>

If your package.json contains:

"scripts": {
  "start": "node index.js"
}

You can run:

bun run start

5. Using Bun as a Bundler​

Step 1: Build Your Application​

Bun includes a fast JavaScript bundler. To bundle files:

bun build src/index.js --outdir=dist

This command creates an optimized, production-ready build in the dist directory.

Step 2: Use Advanced Options​

Bun’s bundler supports additional options for customization:

bun build src/index.js --outdir=dist --minify --sourcemap
  • --minify: Reduces file size for production.
  • --sourcemap: Generates source maps for debugging.

6. Testing with Bun​

Step 1: Write Tests​

Create a simple test file test.js:

import { describe, it, expect } from "bun:test";

describe("Addition", () => {
  it("adds two numbers", () => {
    expect(1 + 1).toBe(2);
  });
});

Step 2: Run Tests​

Run tests with the following command:

bun test

Bun’s testing library provides a fast and built-in solution for unit testing.

7. Deploying Bun Applications​

Step 1: Build for Production​

Prepare your application for deployment by bundling it:

bun build src/index.js --outdir=build --minify

Step 2: Serve the Application​

Use Bun’s built-in server to serve static files or API endpoints:

bun run server.js

Alternatively, deploy your build directory using platforms like Vercel, Netlify, or your own server.

8. Troubleshooting Common Issues​

  1. Command Not Found:

    • Ensure Bun is added to your PATH.
    • Restart your terminal after installation.

  2. Dependency Errors:

    • Use bun install to refresh your dependencies.
    • Check for typos in package names.

  3. Build Failures:

    • Verify the file paths and bundler options.
    • Ensure source files are properly structured.

9. Next Steps​

  1. Learn Bun’s Advanced Features:

    • Explore Bun’s API for custom workflows.
    • Use Bun’s REPL for quick experimentation.

  2. Contribute to Bun:

    • Join the community on GitHub and contribute to its development.

  3. Build and Share:

    • Create projects using Bun and share them with the community.

10. Recap​

Bun streamlines the JavaScript development experience with its fast runtime and integrated tools.

Whether you’re building applications, testing code, or deploying projects, Bun offers a modern solution for developers.

Check out our next guide below!