feat: support suggestions in pattern error messages

danielroe · danielroe · commit e54d6a4023f2 · 2026-03-04T12:55:02.000Z
diff --git a/README.md b/README.md
@@ -46,6 +46,10 @@ export default {
 - Install dependencies using `pnpm install`
 - Run interactive tests using `pnpm dev`
 
+## Acknowledgements
+
+Some features in impound were inspired by [TanStack Start's import protection](https://tanstack.com/start/latest/docs/framework/react/guide/import-protection).
+
 ## License
 
 Made with &#10084;&#65039;
diff --git a/src/index.ts b/src/index.ts
@@ -32,8 +32,8 @@ export interface ImpoundMatcherOptions {
    * Return `false` to allow the import and suppress the default error/warning.
    */
   onViolation?: (info: ImpoundViolationInfo) => boolean | void
-  /** An array of patterns to prevent being imported, along with an optional warning to display.  */
-  patterns: [importPattern: string | RegExp | ((id: string, importer: string) => boolean | string), warning?: string][]
+  /** An array of patterns to prevent being imported, along with an optional warning and suggestions to display.  */
+  patterns: [importPattern: string | RegExp | ((id: string, importer: string) => boolean | string), warning?: string, suggestions?: string[]][]
 }
 
 export interface ImpoundSharedOptions {
@@ -72,15 +72,18 @@ export const ImpoundPlugin = createUnplugin((globalOptions: ImpoundOptions) => {
 
         const relativeImporter = isAbsolute(importer) && globalOptions.cwd ? relative(globalOptions.cwd, importer) : importer
         const logError = options.error === false ? console.error : this.error.bind(this)
-        for (const [pattern, warning] of options.patterns) {
+        for (const [pattern, warning, suggestions] of options.patterns) {
           const usesImport = pattern instanceof RegExp
             ? pattern.test(id)
             : typeof pattern === 'string'
               ? pattern === id
               : pattern(id, relativeImporter)
 
           if (usesImport) {
-            const message = `${typeof usesImport === 'string' ? usesImport : (warning || 'Invalid import')} [importing \`${id}\` from \`${relativeImporter}\`]`
+            let message = `${typeof usesImport === 'string' ? usesImport : (warning || 'Invalid import')} [importing \`${id}\` from \`${relativeImporter}\`]`
+            if (suggestions?.length) {
+              message += `\n\nSuggestions:\n${suggestions.map(s => `  - ${s}`).join('\n')}`
+            }
             if (options.onViolation?.({ id, importer: relativeImporter, message }) === false) {
               continue
             }
diff --git a/test/index.test.ts b/test/index.test.ts
@@ -118,6 +118,19 @@ describe('impound plugin', () => {
     const result = await process(code('bar'), { patterns: [['bar', '"bar" is a dangerous library and should never be used.']] }) as RollupError
     expect(result.message).toMatchInlineSnapshot(`"[plugin impound] "bar" is a dangerous library and should never be used. [importing \`bar\` from \`entry.js\`]"`)
   })
+
+  it('appends suggestions to error message', async () => {
+    const result = await process(code('bar'), {
+      patterns: [['bar', 'Server-only import', ['Use a server function instead', 'Move this import to a .server.ts file']]],
+    }) as RollupError
+    expect(result.message).toMatchInlineSnapshot(`
+      "[plugin impound] Server-only import [importing \`bar\` from \`entry.js\`]
+
+      Suggestions:
+        - Use a server function instead
+        - Move this import to a .server.ts file"
+    `)
+  })
 })
 
 async function process(code: string, opts: ImpoundOptions, importer = 'entry.js') {
