{"record":{"id":"c72ac07cdf3932f0","repo":"biomejs/biome","slug":"this-package-is-intended-to-be-used-in-biome-js-pl","errorCode":null,"errorMessage":"This package is intended to be used in Biome JS plugins, did you mean `@biomejs/js-api`?","messagePattern":"This package is intended to be used in Biome JS plugins, did you mean `@biomejs/js-api`\\?","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@biomejs/plugin-api/index.js","lineNumber":1,"sourceCode":"throw new Error(\n\t\"This package is intended to be used in Biome JS plugins, did you mean `@biomejs/js-api`?\",\n);\n","sourceCodeStart":1,"sourceCodeEnd":4,"githubUrl":"https://github.com/biomejs/biome/blob/7529811358079edb5a2a9d4a5f67a9f639a63f3a/packages/@biomejs/plugin-api/index.js#L1-L4","documentation":"The runtime entry point of the npm package @biomejs/plugin-api is a single unconditional throw (plugin-api/index.js:1-3). The package exists to provide type definitions to JavaScript plugin files executed by Biome's own plugin loader; it is not a library. Importing it for its value at runtime evaluates the module and throws immediately, with a message pointing you to the real public API package.","triggerScenarios":"Any 'import ... from \"@biomejs/plugin-api\"' or require() that is not erased at compile time (i.e. not 'import type'): app code, scripts, config files, or editor auto-import picking the wrong package name.","commonSituations":"A developer wants Biome's programmatic API and guesses the package name; an IDE auto-import suggestion selects @biomejs/plugin-api instead of @biomejs/js-api; the dependency was added to package.json by mistake or by autocomplete.","solutions":["Use @biomejs/js-api for the public programmatic API: const biome = await Biome.create({ distribution: Distribution.NODE }).","When authoring Biome JS plugins, reference @biomejs/plugin-api only with type-only imports ('import type { ... }') that are erased at build time.","Remove @biomejs/plugin-api from your application dependencies if it was installed for the public API."],"exampleFix":"// before\nimport { Biome } from \"@biomejs/plugin-api\";\n\n// after\nimport { Biome, Distribution } from \"@biomejs/js-api\";\nconst biome = await Biome.create({ distribution: Distribution.NODE });","handlingStrategy":"validation","validationCode":"// Fail at build time instead of runtime: scan sources for runtime imports of the plugin-only package\nimport { execSync } from \"node:child_process\";\n\nlet hits = \"\";\ntry {\n\thits = execSync('grep -rlE \"import [^']*\\{[^}]*\\} from .*@biomejs/plugin-api\" src/ || true', {\n\t\tencoding: \"utf-8\",\n\t});\n} catch {}\nif (hits.trim()) {\n\tthrow new Error(\n\t\t\"@biomejs/plugin-api must only be imported with 'import type' (Biome JS plugins). \" +\n\t\t\t\"For the public API use @biomejs/js-api. Offending files:\\n\" + hits,\n\t);\n}","typeGuard":null,"tryCatchPattern":"// Redirect an accidental plugin-api import to the real API package\nasync function loadBiome() {\n\ttry {\n\t\treturn await import(\"@biomejs/plugin-api\");\n\t} catch (err) {\n\t\tif (err instanceof Error && err.message.includes(\"@biomejs/js-api\")) {\n\t\t\treturn import(\"@biomejs/js-api\"); // the intended package\n\t\t}\n\t\tthrow err;\n\t}\n}","preventionTips":["Memorize the split: @biomejs/js-api is the public programmatic API; @biomejs/plugin-api is types-only for files Biome loads as plugins.","Use 'import type' exclusively when referencing plugin-api, so the import is erased and never evaluates.","Watch editor auto-import suggestions; they frequently pick the similarly named package."],"tags":["npm","package-import","javascript","typescript","api"],"backgroundTag":"incorrect-package-import","analyzedSha":"7529811358079edb5a2a9d4a5f67a9f639a63f3a","analyzedAt":"2026-08-16T22:13:27.842Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}