biomejs/biome · error · Error

This package is intended to be used in Biome JS plugins, did

Error message

This package is intended to be used in Biome JS plugins, did you mean `@biomejs/js-api`?

What it means

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.

Source

Thrown at packages/@biomejs/plugin-api/index.js:1

throw new Error(
	"This package is intended to be used in Biome JS plugins, did you mean `@biomejs/js-api`?",
);

View on GitHub (pinned to 7529811358)

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.

Example fix

// before
import { Biome } from "@biomejs/plugin-api";

// after
import { Biome, Distribution } from "@biomejs/js-api";
const biome = await Biome.create({ distribution: Distribution.NODE });

Defensive patterns

Strategy: validation

Validate before calling

// Fail at build time instead of runtime: scan sources for runtime imports of the plugin-only package
import { execSync } from "node:child_process";

let hits = "";
try {
	hits = execSync('grep -rlE "import [^']*\{[^}]*\} from .*@biomejs/plugin-api" src/ || true', {
		encoding: "utf-8",
	});
} catch {}
if (hits.trim()) {
	throw new Error(
		"@biomejs/plugin-api must only be imported with 'import type' (Biome JS plugins). " +
			"For the public API use @biomejs/js-api. Offending files:\n" + hits,
	);
}

Try / catch

// Redirect an accidental plugin-api import to the real API package
async function loadBiome() {
	try {
		return await import("@biomejs/plugin-api");
	} catch (err) {
		if (err instanceof Error && err.message.includes("@biomejs/js-api")) {
			return import("@biomejs/js-api"); // the intended package
		}
		throw err;
	}
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

Unknown distribution: ${distribution}

AI-assisted analysis of biomejs/biome@7529811358 (2026-08-16). Data as JSON: /api/errors/c72ac07cdf3932f0. Report an issue: GitHub.