Import npm libraries

This topic explains how to incorporate external React component libraries from npm into your project. You'll learn how to install and import UI components from popular React libraries.

Use npm to install the external library. For example, to install React Icons, use the following command:

npm install react-icons

If you are working in Reunite, you can install the library by adding it to the package.json file.

{
  // ...
  "dependencies": {
    // existing dependencies
    "react-icons": "^4.11.0"
  }
}

Follow the steps in Run a specific product version in Reunite to create a package.json file if you don't have one already.

You might need to install libraries from private npm registries (such as Artifactory, AWS CodeArtifact, or GitHub Packages). Configure registry access using either .npmrc or bunfig.toml files.

Create a .npmrc file in your project root:

@myorg:registry=https://registry.myorg.com/
//registry.myorg.com/:_authToken=${NPM_TOKEN}

For enhanced flexibility, create a bunfig.toml file in your project root:

[install.scopes]
# Using environment variables for credentials
"@myorg" = { token = "$NPM_TOKEN", url = "https://registry.myorg.com/" }

# Alternative with username/password
"@mycompany" = {
  username = "$NPM_USERNAME",
  password = "$NPM_PASSWORD",
  url = "https://registry.mycompany.com/"
}

Store your registry credentials as environment variables:

• For local development, add them to your .env file (do not commit secrets to Git):

  NPM_TOKEN=your-private-token-here
  NPM_USERNAME=your-username
  NPM_PASSWORD=your-password
  

• For Reunite projects, add them through the Settings > Environment variables page and mark them as secrets. Reunite supports environment variable names that start with NPM_ for private package registries.

For more information about managing environment variables, see Use environment variables.

After installation, you can import components directly in your React files, as in the following example:

import * as React from 'react';
import { FaHeart, FaThumbsUp } from 'react-icons/fa';

export function MyComponent() {
  return (
    <div>
      <FaHeart color="red" size={24} />
      <FaThumbsUp color="blue" size={24} />
    </div>
  );
}

For more information about how to register and use custom Markdoc tags, see Build markdoc tags.

To use external components within Markdoc, you'll need to register them in your schema, as in the following example:

// @theme/markdoc/schema.ts
import type { MarkdocTagSchema } from '@redocly/theme/markdoc/tags/types';

export const tags: Record<string, MarkdocTagSchema> = {
  // ... existing tags ...
  reactIcon: {
    render: 'ReactIcon',
    attributes: {
      name: {
        type: 'string',
        required: true,
      },
      size: {
        type: 'number',
        default: 24,
      },
      color: {
        type: 'string',
        default: 'currentColor',
      },
    },
  },
};

You also need to export your components as in the following example:

import * as React from 'react';
import { FaHeart, FaThumbsUp } from 'react-icons/fa';

export function ReactIcon({ name, size = 24, color = 'currentColor' }) {
  const icons = {
    heart: FaHeart,
    thumbsUp: FaThumbsUp,
  };

  const IconComponent = icons[name];
  return <IconComponent size={size} color={color} />;
}

You can use the icon tag in your Markdoc files, as in the following example:

{% reactIcon name="heart" color="red" /%}
{% reactIcon name="thumbsUp" color="blue" size=32 /%}

• Use environment variables - Configure secure credentials for private registry access using environment variables
• Build Markdoc tags - Create reusable Markdoc tags using imported npm libraries for enhanced functionality
• Icon tag - Use Redocly's built-in icon system and learn patterns for extending it with external icon libraries
• Extend with code - Discover customizable components and customization options for your project