> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/react-icons/react-icons/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Install Node.js">
    React Icons requires Node.js 14 or higher:

    ```bash theme={null}
    node --version  # Should be v14.0.0 or higher
    ```

    Download from [nodejs.org](https://nodejs.org/) if needed.
  </Step>

  <Step title="Install Yarn">
    The project uses Yarn (v3.2.4+) as the package manager:

    ```bash theme={null}
    npm install -g yarn
    yarn --version
    ```
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/react-icons/react-icons.git
    cd react-icons
    ```
  </Step>
</Steps>

## 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:

```bash theme={null}
./build-script.sh
```

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

## Building the Main Package

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    yarn
    ```

    This installs dependencies for all packages in the monorepo.
  </Step>

  <Step title="Navigate to the package">
    ```bash theme={null}
    cd packages/react-icons
    ```
  </Step>

  <Step title="Fetch icon sources">
    Download SVG files from upstream icon repositories:

    ```bash theme={null}
    yarn fetch
    ```

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

  <Step title="Build the icons">
    Generate React components from SVG files:

    ```bash theme={null}
    yarn build
    ```

    This creates:

    * `lib/` - Compiled JavaScript modules
    * Icon components for each pack (e.g., `fa/`, `md/`, `hi/`)
  </Step>
</Steps>

## Build Scripts Explained

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

### Fetch Icons

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
yarn check
```

Validates that:

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

### Type Check

```bash theme={null}
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:

<Steps>
  <Step title="Build react-icons package">
    ```bash theme={null}
    cd packages/react-icons
    yarn fetch && yarn build
    ```
  </Step>

  <Step title="Start the demo app">
    ```bash theme={null}
    cd ../demo
    yarn start
    ```

    The demo app runs at [http://localhost:3000](http://localhost:3000)
  </Step>

  <Step title="Make changes and rebuild">
    Edit source files in `packages/react-icons/src/`, then rebuild:

    ```bash theme={null}
    cd packages/react-icons
    yarn build
    ```

    Refresh the demo app to see changes.
  </Step>
</Steps>

## Build Configuration

### Babel Configuration

React Icons uses Babel for transpilation with two configs:

**CommonJS** (`babel.config.commonjs.json`):

```json theme={null}
{
  "presets": [
    ["@babel/preset-env", { "modules": "commonjs" }],
    "@babel/preset-react",
    "@babel/preset-typescript"
  ]
}
```

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

```json theme={null}
{
  "presets": [
    ["@babel/preset-env", { "modules": false }],
    "@babel/preset-react",
    "@babel/preset-typescript"
  ]
}
```

### TypeScript Configuration

`tsconfig.json` enables strict type checking:

```json theme={null}
{
  "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:

```bash theme={null}
# Edit src/icons/index.ts to include only desired packs
# Then run:
yarn fetch && yarn build
```

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

## Testing Your Build

<Steps>
  <Step title="Create a test project">
    ```bash theme={null}
    npx create-react-app test-app
    cd test-app
    ```
  </Step>

  <Step title="Link your local build">
    ```bash theme={null}
    cd path/to/react-icons/packages/react-icons
    yarn link

    cd path/to/test-app
    yarn link react-icons
    ```
  </Step>

  <Step title="Test importing icons">
    ```jsx App.js theme={null}
    import { FaBeer } from "react-icons/fa";

    function App() {
      return (
        <div>
          <h1>Test <FaBeer /></h1>
        </div>
      );
    }

    export default App;
    ```
  </Step>

  <Step title="Verify tree-shaking">
    ```bash theme={null}
    yarn build
    ```

    Check the bundle size to ensure only imported icons are included.
  </Step>
</Steps>

## Building the Documentation Site

The documentation site is built with Astro:

<Steps>
  <Step title="Build react-icons first">
    ```bash theme={null}
    cd packages/react-icons
    yarn fetch && yarn build
    ```
  </Step>

  <Step title="Start the preview site">
    ```bash theme={null}
    cd ../preview-astro
    yarn start
    ```

    Access the site at [http://localhost:4321](http://localhost:4321)
  </Step>
</Steps>

<Note>
  The project is not actively accepting PRs for the preview site at this time.
</Note>

## Common Build Issues

<AccordionGroup>
  <Accordion title="Out of memory errors">
    Building all icons requires significant memory. Increase Node.js heap size:

    ```bash theme={null}
    export NODE_OPTIONS="--max-old-space-size=4096"
    yarn build
    ```
  </Accordion>

  <Accordion title="Git fetch failures">
    If fetching icons fails, check your internet connection and GitHub access:

    ```bash theme={null}
    # Test Git access
    git ls-remote https://github.com/FortAwesome/Font-Awesome.git
    ```

    Some icon repositories may be rate-limited or temporarily unavailable.
  </Accordion>

  <Accordion title="TypeScript errors">
    Ensure you're using a compatible TypeScript version:

    ```bash theme={null}
    yarn add -D typescript@^5.9.2
    yarn type-check
    ```
  </Accordion>

  <Accordion title="Missing SVG files">
    If build complains about missing SVGs, re-fetch icons:

    ```bash theme={null}
    rm -rf icons/
    yarn fetch
    ```
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Contributing" icon="code-pull-request" href="/advanced/contributing">
    Learn how to contribute your changes
  </Card>

  <Card title="Adding Icon Sets" icon="square-plus" href="/advanced/adding-icon-sets">
    Add new icon packs to the library
  </Card>
</CardGroup>