Forem: Michael

Supercharge Frontend Development with MSW, OpenAPI, and AI-Generated Mocks

Michael — Thu, 12 Jun 2025 21:10:21 +0000

Introduction

Modern web development calls for close interaction with backend APIs. Frontend development might be stalled while waiting for backend APIs to be ready. Mocking helps close that gap, although maintaining mocks by hand becomes difficult, especially as APIs evolve. This is where the power of the Mock Service Worker (MSW) and the OpenAPI Specification (OAS) comes into play. It enables you to spin up accurate, realistic mocks with minimal manual effort and full alignment with your API contract, speeding up frontend development.

This post will show how to automatically create MSW handlers using an OpenAPI spec, generate mock data, and add realistic delays to the mock server.

What is the OpenAPI specification?

The OpenAPI Specification (OAS) is a machine-readable contract for your API. You define everything up front: endpoints, query params, request body, responses, and data shapes instead of relying on manual communication or trial-and-error. Not only is it useful for backend developers, but it also unlocks auto-generated mock servers, documentation (like swagger), auto-generated code and more. In short, OpenAPI provides consistency, clarity, and automation to the often messy world of API development and improves communication between frontend and backend teams.

In this article, we'll use an existing RESTful API—swapi.tech—to explore what MSW, OpenAPI, and AI can do together.

What is MSW?

Mock Service Worker (MSW) lets you intercept network requests directly in the browser or Node.js, without modifying your application code. It runs in the background (as a service worker) and responds with mock data, enabling you to build, test, and debug applications even when the backend API is unavailable or not present at all.

You can combine MSW with data generators like faker.js or rosiejs. In this post, we'll use faker.js, as it's the more up-to-date and actively maintained library.

Note: Before diving into setup, focus on this key point from the MSW docs:

"It’s important to approach those handlers from the server’s perspective since, effectively, you are describing how the server should behave in a particular scenario."

Even though the logic lives in your frontend codebase, think of MSW handlers as mimicking your backend logic, not extending your frontend.

🛠️ Setup

We are building a Star Wars app using data from swapi.tech, but:

API is not ready yet
The API has rate limits or downtime
You want to work offline
You need to test edge or non-existent cases

Instead of recreating backend controllers, you can mock the API using MSW, generate realistic data with faker.js, and describe endpoints using an OpenAPI spec.

1. ✅ Define the OpenAPI spec

We'll use OpenAPI 3.1.1. First, create a folder and YAML file for your spec:

mkdir docs && touch swapi-openapi-spec.yaml

openapi: "3.1.1"
info:
  title: "swapi.tech – Star Wars API"
  version: "1.0.0"
  description: "Public read-only Star Wars data as described on swapi.tech"
servers:
  - url: https://www.swapi.tech/api

We'll later extend this with paths and schemas. swapi.tech is simple enough to map quickly. For more complex APIs, more time is needed to fully understand relationships between resources.

🔗 Resource endpoints

GET /people
GET /people/{id}
GET /planets
GET /planets/{id}
GET /starships
GET /starships/{id}
GET /films
GET /films/{id}
GET /species
GET /species/{id}
GET /vehicles
GET /vehicles/{id}

👨‍🚀 Entities

People
Planets
Films
Species
Starships
Vehicles

We then add schemas and query parameters like this:

paths:
  /people:
    get:
      summary: List all people
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        "200":
          description: "List of people"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeopleListResponse"
components:
  schemas:
    BaseApiResponse:
      type: object
      properties:
        message:
          type: string
          example: "ok"
        apiVersion:
          type: string
          example: "1.0"
        timestamp:
          type: string
          format: date-time
        support:
          type: object
          properties:
            contact:
              type: string
              example: "admin@swapi.tech"
            donate:
              type: string
              example: "https://www.paypal.com/donate/..."
            partnerDiscounts:
              type: object
        social:
          type: object
          properties:
            discord:
              type: string
            reddit:
              type: string
            github:
              type: string
    PeopleListResponse:
      allOf:
        - $ref: "#/components/schemas/BaseApiResponse"
        - type: object
          properties:
            total_records:
              type: integer
            total_pages:
              type: integer
            previous:
              type: [string, "null"]
            next:
              type: [string, "null"]
            results:
              type: array
              items:
                $ref: "#/components/schemas/ListItem"
    ListItem:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
        url:
          type: string

In the above code snippet, we defined two main properties for the specification. Paths including endpoint identifiers and the actual method type (GET verb), query parameters that the endpoint can accept, and a success response (status "200").

Another important attribute is components which allows you to design the spec's entities in a reusable manner and improves the spec's readability.

💡 Tip: Use 42Crunch VS Code extension to preview your OpenAPI spec as Swagger UI.

Generating models and mocking

⚖️ Setup MSW

🤖 AI-Powered models (or not)

The OpenAPI standard's strength lies in its interoperability across various tools. So if you do not care about your models' privacy or OpenAPI spec privacy, you can share your OpenAPI with an AI model (ChatGPT, Claude, GitHub CoPilot, Cursor, etc.) and request it to export all models and query params from the OpenAPI spec to typescript.

Nevertheless, for enterprise-grade or schema-rich APIs, general-purpose language models are prone to hallucinations and structural inconsistencies. So instead of using a generic AI model, you can utilize deterministic generators like openapi-typescript or similar libraries that will generate the TypeScript models out of a given OpenAPI spec. Some of the benefits of using such a library are

Local-first model generation with no data leakage
Predictable and verifiable outputs
Open-source flexibility for introspection, extension (via forking), and community contribution

🤖 AI-Powered mocks (or not)

Install msw-auto-mock:

npm install msw-auto-mock --save-dev

Configure your AI model in package.json:

"msw-auto-mock": {
  "ai": {
    "model": "gpt-4o",
    "enable": true,
    "provider": "openai",
    "openai": {
      "apiKey": "process.env.OPENAI_API_KEY"
    }
  }
}

Run the generator:

npx msw-auto-mock ./docs/mock-swapi-openapi.json -o ./mock

💡 Tip: Alternatively if you don't want to use the ai feature, you can simply by pass the configuration of msw-auto-mock in the package.json and library will generate dynamic mocks primarily based on fakerjs._

🔄 Conditionally enable mocking

// index.js
export async function enableMocking() {
  if (process.env.NODE_ENV !== 'development') return;
  const { worker } = await import('./browser');
  return worker.start();
}

// main.tsx
import { enableMocking } from './mock';

enableMocking().then(() => {
  console.log('Mocking enabled');
  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <App />
    </StrictMode>
  );
});

🏢 Exclude MSW from production builds

Something important to consider is that we do not need the MSW for production builds; therefore, we can opt out of all MSW modules from our final bundle file. In Vite configuration, this can be done by creating a custom rollup function called manualChunks that will parse all chunk IDs, which parses all chunk IDs (where each ID is the file path). If the chunk belongs to MSW, we mark it as an external package and exclude it from the final bundled file. Finally, we add an esbuild utility to treeshake any remaining MSW initialization code for the production build.

export default defineConfig(({ command }) => {
  const isProductionBuild = process.env.NODE_ENV === "production" && command === "build";
  return {
    plugins: [react(), tsconfigPaths()],
    build: {
      target: "esnext",
      rollupOptions: {
        external: ["@faker-js/faker"],
        output: {
          ...markMSWmodulesAsExternal(isProductionBuild),
        }
      }
    },
    esbuild: {
      pure: treeShakeMSWModules(isProductionBuild)
    }
  };
});

function markMSWmodulesAsExternal(isProductionBuild = false) {
  return isProductionBuild ? {
    manualChunks(id) {
      if (id.includes("msw") || id.includes("/src/mock/")) return "msw";
    }
  } : {};
}

function treeShakeMSWModules(isProductionBuild = false) {
  return isProductionBuild ? ["startMockServiceWorker", "setupWorker", "setupServer"] : [];
}

🎨 Time to build!

Start your app, open localhost, and start building your UI with no backend required — vibe code your Star Wars app 🤖.

MSW logs requests in the browser console:

⏳ Add delay for data loading state

// handlers.js
export const handlers = [
  http.all('/*', async () => {
    await delay(2000);
  }),
  ...
];

After adding delays, your app will naturally reflect real-world latency, which is perfect for testing loading states.

💡 Tip: To protect your frontend application from changes in backend models, use transformation methods that convert server responses to client models—and vice versa. This way, when backend data structures change, you typically only need to update your transform layer.

Example:

Initial data integration using a transform method:

type ResponseData = {
  first_name: string;
  last_name: string;
};

const transformer = (data: ResponseData) => ({
  firstName: data.first_name,
  lastName: data.last_name,
});

Later, if the backend response changes:

type ResponseData = {
  person_details: {
    first_name: string;
    last_name: string;
  };
};

// Only the transformer needs to be updated
const transformer = (data: ResponseData) => ({
  firstName: data.person_details.first_name,
  lastName: data.person_details.last_name,
});

The repository link is in the first comment ⬇️!

Thanks for reading, and may the mocks be with you! 🌟

Runtime environmental variables in Next.js 14

Michael — Thu, 25 Apr 2024 14:25:51 +0000

This post will walk you through how to enable runtime environmental variables for both client and server components in a Dockerized Next.js app deployed on a custom-configured host.

Disclaimer: If you have a Dockerized Next.js application and you want to enable runtime environmental variables, then this post will help you; otherwise, if you use Vercel's cloud infrastructure for your deployments, Next.js documentation got you covered 😎.

Topics

The Goal
The Solution
- Step 1: Configure Server Components and Environmental Variables
- Step 2: Add script tag to main layout file
- Step 3: Create React context
- Step 4: Handle environmental variables in client components
Testing
Cons
Conclusion

The Goal ⭐

One of the most important rules of a 12-factor application and key to continuous integration and development (CI/CD) is the Config rule. It specifies the separation of the code and the environmental variables, which makes an app agile to configuration changes and reduces its builds.

With the release of Next.js 14 and the unstable_noStore utility, we now have a new method of handling runtime environmental variables and implementing the "Build once, deploy many" strategy. In general, the goal of this strategy is to enable us to deploy a Docker image in multiple environments (e.g. production, staging, or development) by simply changing our configuration environmental variables based on the requirements of each environment, thus preventing the need to create a new image for each.

The graphic below shows how the aforementioned strategy will function with a Dockerized Next.js 14 application.

Static vs. runtime environmental variables

To get the following behavior in a Next.js app, we need to enable runtime environments. Our app uses two types of environmental variables:

runtime, which are evaluated during the application's runtime and should be changed dynamically each time it refreshes
static, which are only evaluated during build time and must be rebuilt to change their value.

So, in this post, we will go over how to handle runtime variables in our app's end-to-end flow.

Until the time of writing, there is no official example of how to enable runtime environmental variables in a Dockerized Next.js app, as utilizing unstable_noStore would only dynamically evaluate variables on the server (node.js runtime). There is also an interesting discussion regarding this topic on GitHub.

Essentially, the Next.js team proposes using an app router and eventually reading runtime environmental variables on each page.tsx route (server component) and passing those values down to the client or components using prop drilling.

❓ However, what if you have multiple deep-nested client components that require access to runtime environmental variables?

We need to figure out how to pass runtime environmental variables to the browser as they change dynamically on the server so that we can have a single source of truth for our environmental variables.

The Solution ✅

Now that we have a basic understanding of what we want to accomplish, we'll look at how to enable runtime environmental variables using the unstable_noStore function.

First and foremost, we can look at the figure below, which represents the solution that we will focus on.

The graphic above demonstrates how we intend to address our primary issue, which is dynamically altering environmental variables in the client's runtime.

If you check the visual example, I have highlighted the steps we will take to attain our goal.

1️⃣ The server component will dynamically read runtime environmental variables and insert them into a script tag.
2️⃣ We will append this script tag to the head of the HTML file, enabling it to run before the user interacts with the UI, eliminating loading states.
3️⃣ Using dom, a React context provider will retrieve runtime environmental variables from the script tag and hydrate the related client components.
4️⃣ To access runtime variables, client components will use the React context.

🔍 Let's now go over each step in more detail. 🔍

1️⃣: Configure Server Components and Environmental Variables

Using the example from the Next.js page, let's create a server component that reads the runtime environments. To keep our configuration simple for the tutorial, we will create a config.ts file with an object containing the values of the environmental variables. In addition, we will define a type for our configuration that reflects the types of each of our environmental variables, making variable management easier within the app. Finally, we will create the server component that will append the script tag to the DOM.

ℹ️ Note: It's worth noting here that we also use a nonce for our script tag, which is critical if you are using CSP rules for your application and want to avoid the browser blocking it.


// config.ts

type RuntimeEnvConfig = {
 my_value?: string;
 app_env_name?: string;
 flags: {
   enableFeatureA?: boolean;
 }
}

export const runtimeEnvConfig:  = {
  my_value: process.env.NEXT_PUBLIC_MY_VALUE,
  app_env_name: process.env.NEXT_PUBLIC_APP_ENV_NAME,
  flags: {
    enableFeatureA: process.env.NEXT_PUBLIC_ENABLE_FEATURE_A
  } 
}

// EnvVariablesScript.tsx

import { unstable_noStore as noStore } from 'next/cache';
import { runtimeEnvConfig } from './config.ts';

export default function EnvVariablesScript() {
  noStore();

  const nonce = headers().get('x-nonce');

  return <script id="env-config" nonce={nonce || ''}
      dangerouslySetInnerHTML={{
        __html: JSON.stringify(runtimeEnvConfig),
      }}  />;

}

2️⃣: Add script tag to main layout file

The component that renders the environmental variables script should be included in the app router's main layout.tsx files so that the script can be rendered to the domain as soon as possible. API keys or third-party integration urls, such as authentication configuration, may be environmental variables that client components should have access to before becoming interactive in order to avoid loading states. Therefore, the script tag should be included in the HTML document's <head /> section. This will include our script in the critical rendering path, requiring the browser to execute it before our web app becomes interactive for the users.

// app/layout.tsx

const RootLayout: FC<{ children: ReactNode }> = ({ children }) => {
  return (
    <html lang="en">
      <head>
        <EnvVariablesScript />
      </head>
      <body>
        {children}
      </body>
    </html>
  );
};

export default RootLayout;

3️⃣: Create React context

Steps 1️⃣ and 2️⃣ are about the server-side work that we need to do. Now that the server work is complete, we can move on to the client-side implementation.

In this stage, we'll develop a React context to keep the client components hydrated with runtime environmental variables.

'use client';

const defaultEnvVariables = {};

const EnvVariablesClientContext = createContext<EnvVariablesClientConfig>(defaultEnvVariables);

type EnvClientProviderProps = {
  children: ReactNode;
};

export const EnvVariablesClientProvider: React.FC<RuntimeEnvConfig> = ({ children }) => {
  const runtimeEnvVariables = {}; // temporary value

  return <EnvVariablesClientContext.Provider value={runtimeEnvVariables}>{children}</EnvVariablesClientContext.Provider>;
};

export const useEnvVariablesClientConfig = (): EnvVariablesClientConfig => {
  if (EnvVariablesClientContext === undefined) {
    throw new Error('useEnvVariablesClientConfig must be used within an EnvVariablesClientProvider');
  }

  return useContext(EnvVariablesClientContext);
};

Based on the code example above, we created a new context, a provider, and a hook for it, allowing us to simply and safely handle the context's value across our app. For the time being, our provider will persist an empty object via runtimeEnvVariables, as shown in the code.

4️⃣: Handle environmental variables in client components

Now, using DOM manipulation, we can make our context provider of greater use to our app. To retrieve runtime environmental variables directly from the provider's value, we must first establish an internal state that will populate the environmental variables during React's componentDidMount life cycle event.

First, let's define our value getter, which will retrieve the added environmental variables from the script tag.

'use client';

export const envScriptId = 'env-config';

const isSSR = typeof window === 'undefined';

export const getRuntimeEnv = (): EnvVariablesClientConfig => {
  if (isSSR) return env;
  const script = window.document.getElementById(envScriptId) as HTMLScriptElement;

  return script ? JSON.parse(script.innerText) : undefined;
};

ℹ️ Note: In the previous example, we used the isSSR check to prevent our getter from running during SSR since both the client and server components will be invoked and the DOM won't yet be ready.

Next, we'll define the internal state that will allow us to hydrate the children's components using the runtime environmental variables on mount.

export const EnvVariablesClientProvider: React.FC<EnvClientProviderProps> = ({ children }) => {
  const [envs, setEnvs] = useState<EnvVariablesClientConfig>(defaultEnvVariables);

  useEffect(() => {
    const runtimeEnvs = getRuntimeEnv();
    setEnvs(runtimeEnvs);
  }, []);

  return <EnvVariablesClientContext.Provider value={envs}>{children}</EnvVariablesClientContext.Provider>;
};

Finally, we will add the EnvVariablesClientProvider component to our app's main layout file.

// app/layout.tsx

const RootLayout: FC<{ children: ReactNode }> = ({ children }) => {
  return (
    <html lang="en">
      <head>
        <EnvVariablesScript />
      </head>
      <body>
        <EnvVariablesClientProvider>
          {children}
        </EnvVariablesClientProvider>
      </body>
    </html>
  );
};

export default RootLayout;

This way, we keep our main layout as a server component; as a result, the script tag containing our environmental variables will be generated on the server, eliminating the need for client components to wait for its rendering.

Using environmental variables in client components

We can now use runtime environmental variables on client components by invoking the useEnvVariablesClientConfig hook. As a result, we can now deploy feature A in the demo environment while hiding it in the production environment, eliminating the need for separate builds for each environment. We simply need to set the related environmental variable NEXT_PUBLIC_ENABLE_FEATURE_A=true in the environment's configuration.

const ClientComponent = () => {
  const config = useEnvVariablesClientConfig();

  const isFeatureAEnabled = config.flags?.enableFeatureA;

  return <>
           {isFeatureAEnabled && <p>feature A</p>}
           ...other features
        </>
}

Testing 🔬

Testing custom implementations, such as the current one, might get overwhelming. However, if we think of the test environment as being like a browser's DOM, we can use the same script tag that EnvVariableScript appends to the DOM during test init in the jest.setup.ts file.

import { runtimeEnvConfig } from '...';

beforeEach(() => {
  const envScript = document.createElement('script');
  envScript.setAttribute('id', envScriptId);
  envScript.innerText = JSON.stringify(runtimeEnvConfig);
  document.body.append(envScript);
});

afterEach(() => {
  document.getElementById(envScriptId)?.remove();
});

In some cases, we may want to override our environmental variables based on specific test conditions. For example, if we want to test the previous component to check if it displays the feature A UI, we can simply change the config.flags?.enableFeatureA value for each test case.

import merge from 'lodash/merge';

const overrideRuntimeEnv = (options: any, forceOverride = false) => {
  const script = document.getElementById(envScriptId);
  const existingData = script?.innerText ? JSON.parse(script?.innerText) : undefined;

  if (script) script.innerText = JSON.stringify(existingData && !forceOverride ? merge(existingData, options) : options);
};


it('should hide feature A when related flag is enabled', () => {
  overrideRuntimeEnv({ flags: { enableFeatureA: false } });

  const { container } = render(<ClientComponent />)

    expect(screen.queryByText('feature A')).not.toBeInTheDocument();

})

it('should hide feature A when related flag is missing', () => {
  overrideRuntimeEnv(undefined, true);

  const { container } = render(<ClientComponent />)

    expect(screen.queryByText('feature A')).not.toBeInTheDocument();
})


it('should display feature A when related flag is enabled', () => {
  overrideRuntimeEnv({ flags: { enableFeatureA: true } });
  const { container } = render(<ClientComponent />)

  expect(screen.getByText('feature A')).toBeInTheDocument();
})

Cons 👎

Although the above solution works well for using runtime environmental variables in client components in a dockerized Next.js app, Next.js does not officially support it yet, and using unstable_noStore will have some cons.

It increases the complexity of the application. You should always keep in mind that you will need to maintain and use your own hook to retrieve environmental variable values.
It has a performance cost for the application because the provider must hydrate components with the new configuration values during the 'componentDidMount' lifecycle event.
It adds extra overhead to component testing because it introduces a new parameter to consider.

Conclusion 📋

This post demonstrated how to handle runtime environmental variables for a Dockerized Next.js application using a custom host. This solution, like almost every other in software engineering, has pros and cons, so please comment and provide feedback!
Thank you for reading the post. I hope this helped you solve your issue or come up with your own solution that best suits your needs.

PS: The open source package next-runtime-env provides an interesting and inspiring approach to the same problem.

Handling Icons in React (SVG Factories)

Michael — Thu, 21 Mar 2024 10:49:20 +0000

In my previous post about managing SVG icons in React, I discussed a method for dynamically controlling important SVG properties such as color, aria-roles, and size. This involves using a single-source React component to handle all the related SVG icons in our app.

In this post, we will explore how to build an React library for icons using the higher-order component pattern in React (HOC). This is a simplified approach that is also used by material-ui and fluent ui libraries and is heavily tested.

Disclaimer: Design systems in the scale of MaterialUI or FluentUI use scripting and automated processes to handle SVG icons, including downloading those icons from CDN and automatically generating icon factories.

This approach provides additional control over the SVG icons. Some of the key benefits will be discussed below.

Consistency: Every icon we generate through the factory is wrapped in the same svg element and shares the same properties.

Build time control: Controlling the generation of SVG icons during the build time can provide better performance optimization and a more secure control compared to generating them at runtime.

Testing SVG components: We optimize the size of our snapshots while retaining important data for our tests.

Final Stats: We compared the impact of the SVG factory approach.

Cons: Of course, this approach is not suitable for all use cases, and we ought to look into alternative solutions based on the challenges that we have to tackle.

Conclusion: My final thoughts regarding SVG factory approach and other alternatives.

Consistency

✅ Let's begin constructing our SVG factory. First, let's create a wrapper component that will encapsulate our icons.

const SvgIcon: React.FC = ({ children }) => {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
    >
      {children}
    </svg>
  );
};

❕This component will eventually wrap each of our existing and upcoming SVG icons, ensuring uniform behavior across all of them.

Usage example:

const CloudIcon = () => {

 return <SvgIcon>
          <path d="M3 18H7M10 18H21M5 21H12M16 21H19M8.8 
            15C6.14903 15 4 12.9466 4 10.4137C4 8.31435 5.6 
            6.375 8 6C8.75283 4.27403 10.5346 3 12.6127 
            3C15.2747 3 17.4504 4.99072 17.6 7.5C19.0127 
            8.09561 20 9.55741 20 11.1402C20 13.2719 18.2091 
            15 16 15L8.8 15Z" stroke="#000000" stroke- 
            width="2" stroke-linecap="round" stroke- 
            linejoin="round"/>
         </SvgIcon>
}

🔛 Now that we have our wrapper component set up, let's take advantage of it and include some properties that should be applied to every wrapped SVG icon.

type Props = {
  /* Any valid svg vector */
  children: React.ReactNode;
  /* Any additional css class the of svg icon */
  cssClass?: string;
  /* The width of the svg icon */
  width: number;
  /* The height of the svg icon */
  height: number;
  /* The viewbox of the svg icon */
  viewBox?: string;
};

const SvgIcon: React.FC<Props> = ({
  children,
  viewBox = '"0 0 24 24"',
  width,
  height,
}) => {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      aria-hidden="true"
      role="img"
      className={cssClass}
      width={width}
      height={height}
      viewBox={viewBox}
    >
      {children}
    </svg>
  );
};

ℹ️ We have included some properties that allow us to adjust the size of each icon during runtime. These properties include the ability to dynamically change the width and height, set a default value for the viewport of our SVG icon, and a cssClass prop for future CSS adjustments. Additionally, the children prop will hold all the inner structure of the SVG icon.
You can find more information about controlling SVG icons dynamically in my previous post.

Build time control

🛠️ Now, let's proceed to our SVG factory. The factory function we will create is essentially a higher-order component (HOC) that generates a new component with additional properties.

export function generateSvg(
  path: React.ReactNode,
  displayName: string
): typeof SvgIcon {
  const iconName = `${displayName}Icon`;

  function Svg(props, ref) {
    return (
      <SvgIcon id={iconName} data-testid={`${displayName}Icon`} {...props}>
        {path}
      </SvgIcon>
    );
  }

  if (isProduction) Svg.displayName = iconName;

  return Svg;
}

🛠️ Let's generate a memoized version of the component by using React.memo. This way, the component will not re-render when its props are unchanged.

...
export function generateSvg(...): typeof SvgIcon {
  ...
  return React.memo(Svg);
}

🎉 Now the SVG factory is fully prepared to generate our SVG icon components, ensuring optimal performance and maintaining a consistent structure.

Testing SVG components

🔬 SVG icons can result in larger snapshot files due to the inclusion of their internal XML structure, which is reflected in the component's snapshot file. In these situations, we can omit the vectors from our snap files. One effective method is utilizing the svgr package. For more in-depth information, you can refer to the documentation found here. Once again, additional dependencies will need to be installed in your app.

ℹ️ In order to address this issue for our case, we can improve our SVG factory to efficiently generate the internal structure of an SVG except test environment. Therefore, it is still possible to keep important data from our snapshot files, such as the icon name or additional properties of our SVGs (e.g. the data-testid attribute).

const isTestEnv = process.env.NODE_ENV === 'test';
const mockSvgContent = <path />;
...
export function generateSvg(
  path: React.ReactNode,
  displayName: string
): typeof SvgIcon {
  const iconName = `${displayName}Icon`;

  function Svg(props, ref) {
    const content = isTestEnv ? mockSvgContent : path;

    return (
      <SvgIcon id={iconName} data-testid={`${displayName}Icon`} {...props}>
        {content}
      </SvgIcon>
    );
  }
...
}

ℹ️ Here is an example of a snapshot file with and without the inner SVG structure.

Final Stats

Bundle size using SVG assets and SVGR library.

Total project size: 149.7 kB
Build time: 290 ms

Bundle size using the SVG factory.

Total project size: 148.91 kB
Build time: 273 ms

Overall, the usage of the SVG factory for a single SVG icon has resulted in a reduction of 0.53% in the total bundle size and 5.9% in the build time of the project. Not bad at all 😎!

ℹ️It should be noted that this project is just for demonstration purposes and that the build time or bundle size may differ depending on the configuration of your project.

Cons

The limitations of this approach's use cases, especially in large codebases, are based on our own decisions about how to handle SVG icons. Furthermore, we should highlight that this may not be the best solution for those who want a quick way to add custom SVG icons to their project, and they should definitely use one of the solutions listed above or in my previous post (such as the SVGR package or img html tags).

Conclusion

Demo repository: https://stackblitz.com/edit/vitejs-vite-8c4uok?file=src%2FApp.tsx

Usage:


const CalendarIcon = generateSvg(
  <path
    d="M21 11.5V8.8C21 7.11984 21 6.27976 20.673 5.63803C20.3854 5.07354 19.9265 4.6146 19.362 4.32698C18.7202 4 17.8802 4 16.2 4H7.8C6.11984 4 5.27976 4 4.63803 4.32698C4.07354 4.6146 3.6146 5.07354 3.32698 5.63803C3 6.27976 3 7.11984 3 8.8V17.2C3 18.8802 3 19.7202 3.32698 20.362C3.6146 20.9265 4.07354 21.3854 4.63803 21.673C5.27976 22 6.11984 22 7.8 22H12.5M21 10H3M16 2V6M8 2V6M18 21V15M15 18H21"
    stroke="#101828"
    stroke-width="2"
    fill="none"
    stroke-linecap="round"
    stroke-linejoin="round"
  ></path>,
  'Calendar'
);

function App() {
  return (
    <>
        <CalendarIcon width={16} height={16} />
        <CalendarIcon width={32} height={32} />
        <CalendarIcon width={64} height={64} />
        <CalendarIcon width={128} height={128} />
    </>
  );
}

⭐ In summary, we created an SVG factory to manage all of our SVG files during the build process. When possible, we also established a single source of truth for SVG icons, which:

includes performance enhancements such as React.memo.
adds SEO enhancements such as title and aria-hidden.
streamlines the process of testing SVG icon changes and minimizes the size of snapshot files.

While there is no ideal solution, we should select the strategy that best suits our requirements. As previously noted, there are other options that involve using external packages like SVGR, but this strategy might be helpful if your app has a large number of icons and you truly have to control them efficiently.

Useful links

MUI createSvgIcon factory
Fluent UI createSvgIcon factory
SVGR package
React Higher-order components (legacy)
React memo

Handling SVG Icons in React

Michael — Tue, 25 Apr 2023 22:14:55 +0000

Topics

Understanding SVG icons
- Structure of SVG Icons
- SVG accessibility
- Choosing the difficult route for scalability
Rendering SVG Icons Through a React Component
- Export settings
- Rending the icons through a React component
- Adding size configuration
- Adding the colour configuration
Conclusion

Understanding SVG icons

Scalable Vector Graphics (SVG) is an image format built in the XML markup language that has several advantages over other image file formats, particularly when used for icons, logos, and graphics. Unlike normal image formats (jpeg, gif, etc.), which are pixel-based, SVGs can scale up or down at any resolution using mathematically defined vectors. You can further explore SVGs in the W3C related page.

Here is a simple SVG icon example exported using streamline:

<svg xmlns="http://www.w3.org/2000/svg " viewBox="0 0 2500 2500" height="24" width="24">
 <path d="M13,6.81l-5.95,6a2.48,2.48,0,0,..." 
  fill="none" 
  stroke="currentColor" 
  stroke-linecap="round" 
  stroke-linejoin="round">
 </path>
</svg>

Structure of SVG Icons

We'll be working with small SVG icons like the one above in this article. These icons are frequently used in buttons, notifications, navigation menus, etc., either in place of text or to completely replace text.

When creating these SVGs, it's a good idea to keep the XML format consistent across all icons of our app so that we can manipulate them all in the same way. If we use the evenodd algorithm or outline-stroke option described in the streamline SVG export tool, the XML structure for these SVG icons will be easier to handle.

In order to preserve all the necessary data, this option will aggregate all the inner vectors of the SVG icon into a path element using additional dimensions.

Although we desire access to the inner vectors of the SVG picture, this technique might not be optimal for huge SVG graphics or SVG that are used in animations.

// using evenodd algorithm or outline-stroke option of strealine
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" version="1.1">
    <path d="M 1664.500 0.579 C 1662.850 0.800, 1655.875 
          1.483, 1649 2.096 C 1595.351 6.882, 1536.713 ..." 
          stroke="none" fill="currentColor" 
          fill-rule="evenodd"></path>
</svg>

You may have also noticed that the SVG tag in the example above lacks width and height attributes. When working with SVG images, we don't have to set the width and height of the icon directly. Instead, we can use the viewBox attribute to tell the image where and how it should scale. It also helps keep problems from happening with how the width and height attributes work in different browsers. For instance, while most browsers will scale the image as expected if we specify width="100" and height="auto", Internet Explorer will scale the image differently.

SVG Accessibility

There are several methods for rendering SVG icons in React. There is also a simpler method to completely bypass React by directly adding the SVG's XML code to an HTML file or the JSX code.

However, this method is not optimal, especially when we are dealing with a large number of SVGs in our HTML or JSX. A possible way to address this issue is to save the SVG files locally or online and render them as images using HTML img tags.

<img src="path/to/svg_image.svg" 
     alt="This is my image alt text" 
     title="My image title" />

This will also improve the site's Search Engine Optimization (SEO), since we have a simpler HTML file in our browser for the search engine crawlers to read. Another important thing to remember is that Google Image Search won't show us any inlined SVG images.

Choosing the difficult route for scalability

While the above solves the SEO issues and the existence of large XML files in the browser's HTML, it makes our SVG icons less flexible and less scalable. For instance, we cannot directly change the fill colour of an SVG icon when it is rendered through an img tag. We will have to resort to using alternatives such as filter or mask in CSS, which are difficult to handle and have limited browser support.

As a result, we may render SVG icons directly in HTML, however we have to use some additional aria attributes and XML elements to make them invisible to screen readers if they are decorative icons or to display the appropriate replacement text if they are crucial to the application's user experience.

Adding aria-hidden="true" to remove the icon from the accessibility tree

// aria-hidden="true" is added on svg tag
<svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" version="1.1">
  <path d="M 1664.500 0.579 C 1662.850 0.800, 1655.875 
          1.483, 1649 2.096 C 1595.351 6.882, 1536.713 ..." 
          stroke="none" fill="currentColor" 
          fill-rule="evenodd"></path>
</svg>

Adding role="img" and title text to meaningful icons. The title's text should reflect the icon's behaviour.

// role="img" and aria-labelledby="attachment-svg" is added on svg tag to
// indicate the descriptive title.

<svg role="img" aria-labelledby="attachment-svg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" version="1.1">
   <title id="attachment-svg">Shows the presence of a file attachment</title>
   <path d="M 1664.500 0.579 C 1662.850 0.800, 1655.875 
          1.483, 1649 2.096 C 1595.351 6.882, 1536.713 ..." 
          stroke="none" fill="currentColor" 
          fill-rule="evenodd"></path>
</svg>

Check out this excellent article on accessible SVG and preserving support for older browser versions.

In order to make our example simpler, we will use SVG by removing them from the accessibility tree (using aria-role="true").

Rendering SVG Icons Through a React Component - Step by Step Guide

Disclaimer 1: It should be noted that the usage of the React library for SVG handling is merely indicative; we can use any other framework or library, such as Angular, Vue, Svelte, or vanilla JavaScript/Typescript, instead.

Disclaimer 2: You must have a basic understanding of Typescript and ReactJs in order to follow the upcoming step-by-step tutorial.

Now let's look at how to construct a React component that will manage every SVG icon in our application. Importing SVG icons into react components will be simple if we use CRA (create-react-app), as the created react project will take care of the import details inside. As an alternative, if we are using a custom bundler like webpack, we will need to install the package@svgr/webpack into our project and add it to the bundler's configuration.

// install the package

npm install @svgr/webpack --save-dev

// add it to webpack config
const webpack = require('webpack');

module.exports = {
  entry: './src/index.js',
  module: {
    rules: [
      {
        test: /\.svg$/,
        include: path.resolve(__dirname, 'src/icons'),
        use: ['@svgr/webpack']
      },
    ],
  },
};

Export settings

After establishing all of the project-related configurations, we can use a react component to render our first image in the browser. We should import an icon into our project first. With the help of the streamline tool, we can create a new SVG icon (make sure the Outline-Strokes and Responsive options are checked).

Then copy the XML by clicking the copy button, and then create a new file attachment.svg in the icons dir and paste the copied content there.

Here is the example of the above process. We just render the SVG file as a React component by using the default SVG loader from create-react-app.

Rending the icons through a React component

Although the above process is straightforward and simple, as our application's codebase and the number of SVG icons we manage expand, we may run into problems. We will therefore have various SVG components scattered throughout the code of our application. This could lead to discrepancies in the SVGs' dimensions (width and height), colour, alt-text descriptions, loading times in the browser, and other factors.

Let's create the following configuration in icons/index.ts file.

import { SVGAttributes, VFC } from "react";

export type IconName = "attachment" | "bomb" | "brush" | "clip" | "copy";

type IconConfig = { component: VFC<SVGAttributes<SVGElement>> };

export const svgIconsConfig: Record<IconName, IconConfig> = {
  attachment: { component: AttachmentIcon },
  bomb: { component: BombIcon },
  brush: { component: BrushIcon },
  clip: { component: ClipIcon },
  copy: { component: CopyIcon }
};

You may verify that we have a key-value mapping in the configuration that has been built. Every icon component has a specific key that corresponds to the icon. Another thing to note is that this setup is adaptable and extensible since we can add more properties according to the behaviour of each icon.

After we specified our icons configuration we can create a React component that will use the configuration in order to render the right icon to the dom. The configuration and usage of typescript give us the ability to have typed properties in our Icon component and avoid issues when using the component by passing the wrong properties values.

Adding size configuration

Let's take a step back now and review our configuration once more. We notice right away that our configuration is missing any icon dimensions (width, height).

export const svgIconsConfig: Record<IconName, IconConfig> = {
  attachment: { component: AttachmentIcon },
  ...
}

Therefore, we should think about whether managing icon scaling for each separately is appropriate or if we should handle sizing for all icons through a different setting. Size is a crucial property for img tags and icons, thus we want to be able to directly adjust it.

const BASE_SIZE = 16;

const sizeConfig = {
  sm: {
    w: BASE_SIZE,
    h: BASE_SIZE,
  },
  md: {
    w: BASE_SIZE * 2,
    h: BASE_SIZE * 2,
  },
  xl: {
    w: BASE_SIZE * 3,
    h: BASE_SIZE * 3,
  },
};

In order to prevent our icons from being rendered with incorrect dimensions, we can position our size configuration at the component level rather than hiding it in the icons configuration.

Adding the colour configuration

Lastly, we will enhance the Icon component with a colour property. This enhancement may be challenging because it demands for a consistent XML structure across all of our SVG icons that are rendered by the Icon component.

Let's check the following image,

If the SVG does not adhere to the guidelines for theevenodd algorithm that we specified at the beginning, we will experience inconsistencies in the XML structure of our SVGs and be unable to properly colour them using a single component, or we will need to increase the complexity of the Icon component.

So, handling all SVG icons through a single component and encapsulating the configuration for these icons in a separate module will be a good way to address the concerns highlighted. We will be able to enhance the functionality of all the icons simultaneously through a single source of truth, manage many icons, provide safeguards for appropriately handling those icons, and dynamically change the colour, size, or name of each icon.

Some things to consider when handling SVGs through a single react component

In some circumstances, each SVG will serve a separate purpose in the app, such as handling different graphic animations, background visuals, or a very vast and sophisticated XML structure.

Handling SVG through a single source of truth (configuration & component) is not advised in these circumstances because we will need to handle each image individually.

Conclusion

SVG icon handling in React can be hard, resulting in inconsistencies and code redundancy that will eventually damage the application's performance, scalability, and development experience.

So, if we use a lot of small icons in our app and want them to behave similarly, handling them through a centralised configuration and single source of truth component will help us organise our codebase, improve the overall performance of our icon rendering, and make it scalable for future expansion.

Nevertheless we shouldn't forget that maintaining consistency in our SVG icons XML structure and keeping it as lean as possible utilizing efficient algorithms likeevenodd is the most crucial aspect of managing SVG through a single component.

Note: This post is not supported by any organisation or product and is based on my personal research and experience.

Useful links: