Skip to main content

​
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:
4

Run the Application

Choose your preferred development mode:
Bruno should now be running! The React app will be available in the Electron window.

​
Development Scripts

​
Core Development Commands

# 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

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
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
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
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: 
npm run test:e2e

​
IDE Setup

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us