https://github.com/malekabdelkader/rsbuild-plugin-block-imports
Rsbuild plugin to detect and block forbidden imports during build time.
https://github.com/malekabdelkader/rsbuild-plugin-block-imports
Last synced: 5 months ago
JSON representation
Rsbuild plugin to detect and block forbidden imports during build time.
- Host: GitHub
- URL: https://github.com/malekabdelkader/rsbuild-plugin-block-imports
- Owner: malekabdelkader
- License: mit
- Created: 2025-12-12T15:08:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T16:12:25.000Z (6 months ago)
- Last Synced: 2025-12-23T05:40:08.726Z (6 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/rsbuild-plugin-block-imports
- Size: 54.7 KB
- Stars: 8
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rstack - rsbuild-plugin-block-imports
README
# rsbuild-plugin-block-imports
> Rsbuild plugin to detect and block forbidden imports during build time.
>
[](https://www.npmjs.com/package/rsbuild-plugin-block-imports)
## 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
```bash
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)
```ts
// 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
```ts
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
```ts
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
```ts
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 → 
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:
## 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