Managing SVG Icon Updates Across a Monorepo

As your organization grows, spreading code across multiple applications—often organized within a monorepo—becomes the standard. You might have a Next.js web application, a React Native mobile app, and an internal React admin dashboard, all living under the same repository roof (e.g., using Turborepo or Nx).

One of the most common pain points in this architecture is managing shared assets, specifically SVG icons. When a designer updates the “Settings” icon in Figma, how do you ensure that update propagates seamlessly across all three applications without manual copy-pasting?

Here is the blueprint for managing SVG icon updates across a monorepo.

The Goal: A Single Source of Truth

The objective is to establish a centralized “icons package” within the monorepo workspace. All applications consume this package as a dependency.

Your monorepo structure should look something like this:

/packages
  /ui-icons
    /assets       # Raw SVG files
    /src          # Generated React/React Native components
    package.json
/apps
  /web            # Next.js app (depends on ui-icons)
  /mobile         # React Native app (depends on ui-icons)
  /admin          # Admin portal (depends on ui-icons)

Step 1: Connecting Design to Code (The Handoff)

The biggest bottleneck is getting SVGs out of Figma and into the /packages/ui-icons/assets directory.

The Automated Approach

Instead of manual exports, utilize the Figma API or tools like Figma-Export to create an automated pipeline.

You can set up a GitHub Action that triggers whenever the design team publishes a new version of the “Icons” file in Figma. The action fetches the SVGs and automatically opens a Pull Request in your monorepo, updating the files in /packages/ui-icons/assets.

Naming Conventions

Enforce strict naming conventions in Figma. An icon named `icon / navigation / menu` in Figma should automatically export as `menu.svg`. Using standard kebab-case naming prevents sync issues.

Step 2: The Package Build Pipeline

Once the raw SVGs are in the package, you need a build script that optimizes them and generates the code needed for your applications.

Inside /packages/ui-icons/package.json:

{
  "name": "@mycompany/ui-icons",
  "version": "1.0.0",
  "scripts": {
    "clean": "rm -rf dist",
    "optimize": "svgo -f assets -o optimized-assets",
    "build:react": "svgr -d src/react optimized-assets",
    "build": "pnpm clean && pnpm optimize && pnpm build:react && tsc"
  }
}

This pipeline ensures that every SVG is compressed using SVGO, and then transformed into React components using SVGR.

Step 3: Caching with Turborepo or Nx

In a monorepo, you don’t want to rebuild the icon package every time you run a dev server unless the icons actually changed.

If you are using Turborepo, you can cache this build step. In your turbo.json:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "src/react/**"]
    },
    "@mycompany/ui-icons#build": {
      "inputs": ["assets/**/*.svg"],
      "outputs": ["src/react/**"]
    }
  }
}

Now, Turborepo will skip rebuilding the icon components unless a file inside /assets changes, saving significant CI/CD and local development time.

Step 4: Consuming the Icons

In your consuming applications (e.g., /apps/web/package.json), add the package as a dependency:

"dependencies": {
  "@mycompany/ui-icons": "workspace:*"
}

Then, developers simply import the icons:

import { SettingsIcon } from '@mycompany/ui-icons/react';

export default function Dashboard() {
  return (
    <nav>
      <SettingsIcon className="w-6 h-6 text-slate-500" />
    </nav>
  );
}

Step 5: Handling Updates and Versioning

When the Pull Request generated by your Figma sync is merged into the main branch, the CI/CD pipeline takes over.

If you are using independent versioning (e.g., via Changesets), the merge will trigger a version bump for @mycompany/ui-icons. Because the applications in the monorepo depend on workspace:* (the latest local version), they will automatically use the updated SVGs on their next build. No developers need to manually track down and replace SVG files.

Summary

By creating a dedicated package for icons, automating the Figma handoff, and leveraging monorepo caching tools, you transform icon management from a tedious, error-prone chore into a seamless, invisible pipeline.