Development Setup

Set up your local development environment to contribute to Bruno

Prerequisites

You need Node.js v22.x or the latest LTS version to run Bruno. We use npm workspaces in the project.

Install Node.js

If you’re using nvm (recommended):

# Install and use Node.js v22
nvm install 22
nvm use 22

Alternatively, download Node.js from nodejs.org.

Quick Start

1. Clone the Repository

   git clone https://github.com/usebruno/bruno.git
   cd bruno
   
2. Install Dependencies

   # Use Node.js 22
   nvm use
   
   # Install dependencies
   npm i --legacy-peer-deps
   

   The --legacy-peer-deps flag is required due to peer dependency conflicts in some packages.

3. Build Packages

   Choose one of the following options:

   Option 1: Setup Script (Recommended)

   # Install dependencies and build all packages
   npm run setup
   

   Option 2: Manual Build

   # Build packages individually
   npm run build:graphql-docs
   npm run build:bruno-query
   npm run build:bruno-common
   npm run build:bruno-converters
   npm run build:bruno-requests
   npm run build:schema-types
   npm run build:bruno-filestore
   
   # Bundle JS sandbox libraries
   npm run sandbox:bundle-libraries --workspace=packages/bruno-js
   
4. Run the Application

   Choose your preferred development mode:

   Concurrent (Recommended)

   # Run both React and Electron together
   npm run dev
   

   Separate Terminals

   Terminal 1 - React App

   npm run dev:web
   

   Terminal 2 - Electron App

   npm run dev:electron
   

Bruno should now be running! The React app will be available in the Electron window.

Development Scripts

Core Development Commands

Development

# Run both web and electron concurrently
npm run dev

# Run with hot reload
npm run dev:watch

# Run web app only
npm run dev:web

# Run electron app only
npm run dev:electron

# Debug electron with inspector
npm run dev:electron:debug

Custom Configuration

Custom Electron userData Path

You can customize the Electron userData path in development mode:

ELECTRON_USER_DATA_PATH=$(realpath ~/Desktop/bruno-test) npm run dev:electron

This creates a bruno-test folder on your Desktop and uses it as the userData path, keeping your development data separate from your production Bruno installation.

Troubleshooting

Unsupported Platform Error

If you encounter an Unsupported platform error during npm install:

# Delete all node_modules directories
find ./ -type d -name "node_modules" -print0 | while read -d $'\0' dir; do
  rm -rf "$dir"
done

# Delete all package-lock.json files
find . -type f -name "package-lock.json" -delete

# Reinstall dependencies
npm i --legacy-peer-deps

Build Failures

If package builds fail:

1. Ensure you’re using Node.js v22.x
2. Clear all build artifacts: rm -rf packages/*/dist
3. Run the setup script again: npm run setup

Electron Won't Start

If Electron fails to start:

1. Ensure the web app built successfully
2. Check that all dependencies are installed
3. Try running web and electron separately to identify the issue

Hot Reload Not Working

If hot reload isn’t working:

1. Use npm run dev:watch instead of npm run dev
2. Ensure file watchers aren’t hitting system limits (common on Linux)
3. Restart the development server

Development Tools

Storybook

Bruno uses Storybook for component development:

npm run storybook

This opens Storybook at http://localhost:6006 where you can develop and test UI components in isolation.

End-to-End Testing

Run Playwright E2E tests:

Default Tests

npm run test:e2e

IDE Setup

VS Code (Recommended)

Recommended extensions:

• ESLint: For linting JavaScript/React code
• Prettier: For code formatting
• Tailwind CSS IntelliSense: For Tailwind autocomplete
• styled-components: For styled-components syntax highlighting

ESLint Configuration

Bruno uses ESLint with custom rules. The configuration is already set up in the project.

Next Steps

Now that your development environment is set up:

1. Read about Bruno’s architecture
2. Familiarize yourself with our coding standards
3. Find an issue to work on in GitHub Issues
4. Start contributing!

Run the test suite before making changes to ensure everything works. This gives you a baseline to compare against after your changes.