Skip to main content

​
Prerequisites

Before building GitHub Desktop, ensure you have the required tools installed:
  • Node.js v20.17.0 or later
  • Yarn 1.21.1 or later
  • Python 3.9.x or later
Verify your installation: 
node -v
yarn -v
python --version

​
Initial Setup

1

Fork and Clone

Create a fork of desktop/desktop and clone it to your local machine:
git clone https://github.com/YOUR_USERNAME/desktop.git
cd desktop
2

Install Dependencies

Install all required dependencies:
yarn
This will also run the postinstall script automatically to set up the development environment.

​
Build Commands

​
Development Build

Create a development build with source maps and debugging support: 
yarn build:dev
This command:
  1. Compiles TypeScript with development settings
  2. Bundles the application using webpack
  3. Includes source maps for debugging

​
Production Build

Create an optimized production build: 
yarn build:prod
Production builds use more memory during compilation. The NODE_OPTIONS='--max_old_space_size=4096' flag is automatically set to handle this.

​
Compilation Only

If you only want to compile without building: 
# Development compilation
yarn compile:dev

# Production compilation
yarn compile:prod

​
Running the Application

After building, start the application: 
yarn start
The application will launch with:
  • Chrome DevTools for debugging
  • React DevTools (automatically installed on first run)
  • Hot reload support (press Ctrl/Cmd+Alt+R to reload)

​
Running in Production Mode

To test production mode locally: 
yarn start:prod

​
Background Compilation

When you run yarn start, changes are compiled automatically in the background. Simply reload the app to see your changes.
Exception: Changes in the main-process folder require rebuilding: 
yarn build:dev
yarn start

​
Packaging

Create distributable packages: 
yarn package
This creates platform-specific installers in the out directory.

​
Clean Build

If you encounter build issues, perform a clean build: 
# Clean and rebuild (development)
yarn rebuild-hard:dev

# Clean and rebuild (production)
yarn rebuild-hard:prod
The clean-slate command removes node_modules and all build artifacts. This will require reinstalling all dependencies.

​
Specialized Build Tasks

​
Generate Octicons

Regenerate Octicons from the latest version: 
yarn generate-octicons

​
Validate Electron Version

Ensure you’re using the correct Electron version: 
yarn validate-electron-version

​
Compile Scripts

Compile scripts in the script/ directory: 
yarn compile:script

​
Build Architecture

GitHub Desktop uses:
  • TypeScript: Type-safe JavaScript with strict type checking
  • Webpack: Module bundler for the application
  • Electron: Cross-platform desktop framework
  • React: UI component library

​
Build Configuration

Build configurations are located in:
  • app/webpack.development.ts - Development webpack config
  • app/webpack.production.ts - Production webpack config
  • script/tsconfig.json - TypeScript compiler config for scripts
  • tsconfig.json - Main TypeScript compiler config

​
Troubleshooting

If you encounter build issues, see the Troubleshooting Development Issues guide.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us