impound

Build plugin to restrict import patterns in certain parts of your code-base.

This package is an unplugin which provides support for a wide range of bundlers.

Usage

Install package:

# npm
npm install impound

// rollup.config.js
import { dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import { ImpoundPlugin } from 'impound'

export default {
  plugins: [
    ImpoundPlugin.rollup({
      cwd: dirname(fileURLToPath(import.meta.url)),
      include: [/src\/*/],
      patterns: [
        [/^node:.*/], // disallows all node imports
        ['@nuxt/kit', 'Importing from @nuxt/kit is not allowed in your src/ directory'], // custom error message
        [(id, importer) => id.endsWith('.server') && `Server-only import in ${importer}`] // functional pattern with importer context
      ]
    }),
  ],
}

Import Tracing

Enable trace: true to get rich violation diagnostics with full import chains and code snippets. When enabled, errors are deferred to buildEnd so the complete module graph can be collected first.

ImpoundPlugin.rollup({
  cwd: dirname(fileURLToPath(import.meta.url)),
  trace: true,
  patterns: [
    [/\.server$/, 'Server-only import', ['Use a server function instead', 'Move this import to a .server.ts file']]
  ]
})

Example output:

Invalid import [importing `secret` from `middle.js`]

Trace:
  1. src/routes/index.tsx:2:34 (entry) (import "../features/auth/session")
  2. src/features/auth/session.ts

Code:
  1 | import { logger } from '../utils/logger'
  2 |
> 3 | import { getUsers } from '../db/queries.server'
    |                           ^
  4 |
  5 | export function loadAuth() {

Suggestions:
  - Use a server function instead
  - Move this import to a .server.ts file

Choosing a trace mode

trace: true records the import graph as modules are transformed. Every module gets parsed, and modules an include pattern covers also get their sourcemap built and their source retained, so snippets can point at original source.

A narrow include therefore keeps eager tracing cheap: only modules that could be the importer in a violation are retained.

trace: 'lazy' records nothing, and reads the bundler's own module graph when a violation actually happens.

| | true | 'lazy' | |---|---|---| | Import chain | yes | yes, including dynamic imports | | Code snippet | yes | yes | | Snippet shows | original source | original source on webpack and rspack, otherwise the code the bundler holds | | Per-module cost | parse, plus sourcemap + retain within include | none | | Bundlers | all | all except esbuild |

Lazy reports from buildEnd, and a dev server only calls that when it shuts down, so keep true for dev:

ImpoundPlugin.vite({
  trace: isDev ? true : 'lazy',
  patterns: [[/\.server$/, 'Server-only import']]
})

Lazy reads the graph through getModuleInfo on rollup, vite and rolldown, and through compilation.moduleGraph on webpack and rspack, where the snippet comes from originalSource() and so shows original rather than transformed code. esbuild exposes no module graph to a plugin, so there lazy reports the plain message with no chain or snippet.

With error: true, lazy reports the first violation and fails the build there, so later ones stay unreported until it is fixed. With either mode, onViolation returning false suppresses the report but no longer allows the import: by the time the hook runs, the import has already been replaced by the proxy.

Named imports from a denied module

A denied import is replaced by a proxy module that has only a default export. syntheticNamedExports papers over that on Rollup alone: rolldown, webpack, rspack and esbuild ignore it. So on those, a named import from a denied module can fail with an error naming impound:proxy before impound reports the real violation. It shows up only when the build is allowed to continue past a violation, which means error: false or lazy tracing.

💻 Development

• Clone this repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

Acknowledgements

Some features in impound were inspired by TanStack Start's import protection.

License

Made with ❤️

Published under MIT License.