Building from Source

Learn how to build React Icons from source code for development and testing

Building React Icons from Source

This guide covers how to build React Icons from source, useful for development, testing, or contributing to the project.

Prerequisites

1. Install Node.js

   React Icons requires Node.js 14 or higher:

   node --version  # Should be v14.0.0 or higher
   

   Download from nodejs.org if needed.

2. Install Yarn

   The project uses Yarn (v3.2.4+) as the package manager:

   npm install -g yarn
   yarn --version
   
3. Clone the repository

   git clone https://github.com/react-icons/react-icons.git
   cd react-icons
   

Project Structure

React Icons is a monorepo with multiple packages:

react-icons/
├── packages/
│   ├── react-icons/          # Main package (icons library)
│   ├── demo/                  # Demo app for testing
│   ├── preview-astro/         # Documentation website
│   ├── _react-icons_all/      # All icons package (legacy)
│   └── ts-test/               # TypeScript tests
├── build-script.sh            # Build all packages
├── package.json               # Root package config
└── lerna.json                 # Monorepo config

Quick Build

For a complete build of all packages:

./build-script.sh

This script builds the main package and all related packages. It may take several minutes on first run.

Building the Main Package

1. Install dependencies

   yarn
   

   This installs dependencies for all packages in the monorepo.

2. Navigate to the package

   cd packages/react-icons
   
3. Fetch icon sources

   Download SVG files from upstream icon repositories:

   yarn fetch
   

   This downloads icons from 30+ repositories defined in src/icons/index.ts. First run may take 5-10 minutes.

4. Build the icons

   Generate React components from SVG files:

   yarn build
   

   This creates:

   • lib/ - Compiled JavaScript modules
   • Icon components for each pack (e.g., fa/, md/, hi/)

Build Scripts Explained

The main package has several build scripts defined in package.json:

Fetch Icons

yarn fetch

This script (scripts/fetcher.ts):

1. Reads icon pack definitions from src/icons/index.ts
2. Clones/updates Git repositories for each icon pack
3. Copies SVG files to the icons/ directory
4. Validates icon sources

Build Components

yarn build

The build script (scripts/build.ts):

1. Processes SVG files with SVGO for optimization
2. Converts SVG to React components using GenIcon
3. Generates TypeScript definitions
4. Creates CommonJS and ES Module outputs
5. Builds icon manifests for each pack

Validate Icons

yarn check

Validates that:

• All icon sources are accessible
• SVG files are valid
• No duplicate icon names
• Licenses are documented

Type Check

yarn type-check

Runs TypeScript compiler to verify types without generating output.

Build Output

After building, you’ll find:

packages/react-icons/
├── lib/
│   ├── index.js               # CommonJS entry
│   ├── index.mjs              # ES Module entry
│   ├── index.d.ts             # TypeScript definitions
│   ├── iconBase.js
│   ├── iconContext.js
│   └── iconsManifest.js
├── fa/
│   ├── index.js               # Font Awesome icons
│   ├── index.d.ts
│   └── FaBeer.js, FaCoffee.js, ...
├── md/                        # Material Design icons
├── hi/                        # Heroicons
└── ...                        # Other icon packs

Building for Development

When developing, use the demo app to test changes:

1. Build react-icons package

   cd packages/react-icons
   yarn fetch && yarn build
   
2. Start the demo app

   cd ../demo
   yarn start
   

   The demo app runs at http://localhost:3000

3. Make changes and rebuild

   Edit source files in packages/react-icons/src/, then rebuild:

   cd packages/react-icons
   yarn build
   

   Refresh the demo app to see changes.

Build Configuration

Babel Configuration

React Icons uses Babel for transpilation with two configs:

CommonJS (babel.config.commonjs.json):

{
  "presets": [
    ["@babel/preset-env", { "modules": "commonjs" }],
    "@babel/preset-react",
    "@babel/preset-typescript"
  ]
}

ES Modules (babel.config.esm.json):

{
  "presets": [
    ["@babel/preset-env", { "modules": false }],
    "@babel/preset-react",
    "@babel/preset-typescript"
  ]
}

TypeScript Configuration

tsconfig.json enables strict type checking:

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "ESNext",
    "jsx": "react",
    "strict": true,
    "esModuleInterop": true
  }
}

Building Specific Icon Packs

To build only specific icon packs, modify the build script or fetch only needed sources:

# Edit src/icons/index.ts to include only desired packs
# Then run:
yarn fetch && yarn build

Building all 30+ icon packs generates 40,000+ components and may take significant time and disk space (500MB+).

Testing Your Build

1. Create a test project

   npx create-react-app test-app
   cd test-app
   
2. Link your local build

   cd path/to/react-icons/packages/react-icons
   yarn link
   
   cd path/to/test-app
   yarn link react-icons
   
3. Test importing icons

   App.js

   import { FaBeer } from "react-icons/fa";
   
   function App() {
     return (
       <div>
         <h1>Test <FaBeer /></h1>
       </div>
     );
   }
   
   export default App;
   
4. Verify tree-shaking

   yarn build
   

   Check the bundle size to ensure only imported icons are included.

Building the Documentation Site

The documentation site is built with Astro:

1. Build react-icons first

   cd packages/react-icons
   yarn fetch && yarn build
   
2. Start the preview site

   cd ../preview-astro
   yarn start
   

   Access the site at http://localhost:4321

The project is not actively accepting PRs for the preview site at this time.

Common Build Issues

Out of memory errors

Building all icons requires significant memory. Increase Node.js heap size:

export NODE_OPTIONS="--max-old-space-size=4096"
yarn build

Git fetch failures

If fetching icons fails, check your internet connection and GitHub access:

# Test Git access
git ls-remote https://github.com/FortAwesome/Font-Awesome.git

Some icon repositories may be rate-limited or temporarily unavailable.

TypeScript errors

Ensure you’re using a compatible TypeScript version:

yarn add -D typescript@^5.9.2
yarn type-check

Missing SVG files

If build complains about missing SVGs, re-fetch icons:

rm -rf icons/
yarn fetch

CI/CD Build

The project uses GitHub Actions for CI. See .github/workflows/ for build pipelines.

Key CI steps:

1. Install dependencies with Yarn
2. Lint code with ESLint
3. Type check with TypeScript
4. Fetch icon sources
5. Build packages
6. Run tests

Next Steps

Contributing

Learn how to contribute your changes

Adding Icon Sets

Add new icon packs to the library