rsbuild-plugin-block-imports

Rsbuild plugin to detect and block forbidden imports during build time.

Why?

Sometimes certain imports should not be used in specific contexts. For example, when using Module Federation to expose React components from a Next.js application, certain imports won't work in remote environments:

• next/link - Next.js router integration
• next/image - Next.js image optimization
• next-intl - Next.js internationalization

This plugin scans your source files during build and fails fast with actionable error messages, saving you from runtime errors in production.

Features

• 🔍 Detects forbidden imports with exact file:line:column locations
• 📝 Shows the actual code that caused the error
• 💡 Suggests alternatives for each forbidden import
• 🎨 Colored terminal output for better readability
• ⚙️ Fully configurable - add your own patterns
• 🌳 Tree-shaking aware - notes that unused imports are safe

Installation

npm install rsbuild-plugin-block-imports -D
# or
pnpm add rsbuild-plugin-block-imports -D
# or
yarn add rsbuild-plugin-block-imports -D

Usage

Basic Usage (Next.js)

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginBlockImports, NEXTJS_FORBIDDEN_IMPORTS } from 'rsbuild-plugin-block-imports';

export default defineConfig({
  plugins: [
    pluginBlockImports({
      forbiddenImports: NEXTJS_FORBIDDEN_IMPORTS,
    }),
  ],
});

Custom Forbidden Imports

import { pluginBlockImports } from 'rsbuild-plugin-block-imports';

export default defineConfig({
  plugins: [
    pluginBlockImports({
      forbiddenImports: [
        { 
          pattern: 'my-internal-package', 
          alternative: 'Use the public API instead' 
        },
        { 
          pattern: '@company/server-only', 
          alternative: 'This package is server-side only' 
        },
      ],
    }),
  ],
});

Combining with Defaults

import { pluginBlockImports, NEXTJS_FORBIDDEN_IMPORTS } from 'rsbuild-plugin-block-imports';

export default defineConfig({
  plugins: [
    pluginBlockImports({
      forbiddenImports: [
        ...NEXTJS_FORBIDDEN_IMPORTS,
        { pattern: 'my-custom-import', alternative: 'Use X instead' },
      ],
    }),
  ],
});

Configuration Options

Option	Type	Default	Description
forbiddenImports	ForbiddenImport[]	required	Array of forbidden import patterns
exclude	(string | RegExp)[]	[]	Paths to exclude from checking
failOnError	boolean	true	Whether to fail the build on errors
errorHeader	string	'FORBIDDEN IMPORTS DETECTED'	Custom header for error output
colors	boolean	true	Enable colored terminal output

ForbiddenImport Interface

interface ForbiddenImport {
  /** Import pattern to match (e.g., 'next/link') */
  pattern: string;
  /** Suggested alternative */
  alternative: string;
  /** Optional reason why this import is forbidden */
  reason?: string;
}

Example Output

  ╭─────────────────────────────────────────────────────────────╮
  │  FORBIDDEN IMPORTS DETECTED                                 │
  ╰─────────────────────────────────────────────────────────────╯

  ✖ Forbidden imports detected in source files
    These imports are not allowed in the current build context.

  /src/components/MyComponent.tsx:5:0
    ✖ Forbidden import: next/image
    │ import Image from 'next/image';

  /src/components/MyComponent.tsx:6:0
    ✖ Forbidden import: next-intl
    │ import { useTranslations } from 'next-intl';

  Suggested alternatives:
    • next/image → <img src="..."> with proper sizing
    • next-intl → react-intl, i18next, or react-i18next

  2 error(s) found. Build failed.

Default Next.js Forbidden Imports

The NEXTJS_FORBIDDEN_IMPORTS export includes:

Import	Alternative
next/link	<a href="..."> or react-router Link
next/image	<img src="..."> with proper sizing
next/router	window.location or custom navigation
next/navigation	window.location or custom navigation
next/head	react-helmet or document.head
next/script	<script> tag or useEffect
next/dynamic	React.lazy() + Suspense
next/font	CSS @font-face or Google Fonts
next/headers	Pass headers as props
next/cookies	document.cookie or js-cookie
next-intl	react-intl or i18next
next-auth	Pass auth state as props
next-themes	Custom theme context
next-seo	react-helmet
next-i18next	i18next + react-i18next

Tree Shaking Note

If a forbidden import is present in a file but not actually used in the exposed components, webpack's tree-shaking algorithm will remove it from the final bundle. This means it won't cause runtime errors.

However, we recommend removing them to prevent accidental usage.

To disable build failures and only show warnings, set failOnError: false.

License

MIT