biomejs/biome · error · Error

@biomejs/runtime/plugin is intended to be used in Biome JS p

Error message

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

What it means

This error is thrown by the @biomejs/runtime package's /plugin entry point to stop developers who imported the wrong package. @biomejs/runtime/plugin only exists to be loaded by the Biome plugin host runtime inside Biome JS plugins; application code that wants to control Biome programmatically must use @biomejs/js-api instead. The throw fires immediately at module load so the mistake fails fast.

Source

Thrown at packages/@biomejs/runtime/plugin.js:1

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

View on GitHub (pinned to 3835945f06)

Solutions

1. Install and import @biomejs/js-api instead: `npm install @biomejs/js-api` and use `import * as biome from "@biomejs/js-api"` for programmatic use.
2. If you ARE writing a Biome JS plugin, do not import the runtime entry manually; declare the plugin (e.g. via its manifest/entry) and let Biome's plugin host provide the runtime.
3. Check the import specifier for typos or stale paths after upgrading Biome packages.

Example fix

// before
import { Runtime } from "@biomejs/runtime/plugin";
// after
import * as biome from "@biomejs/js-api";

// Guard: detect the wrong-package import before use
function isJsApiAvailable(mod: any): boolean {
  return typeof mod === "object" && mod !== null && !/runtime\/plugin/.test(import.meta?.url ?? "");
}
if (!isJsApiAvailable(biomeModule)) throw new Error("Use @biomejs/js-api for programmatic Biome access");

function isJsApiModule(mod: unknown): mod is typeof import("@biomejs/js-api") {
  return typeof mod === "object" && mod !== null && "workspace" in (mod as object);
}

try {
  await import("@biomejs/runtime/plugin");
} catch (e) {
  if (e instanceof Error && e.message.includes("@biomejs/js-api")) {
    // fall back to the correct package
    const biome = await import("@biomejs/js-api");
  } else { throw e; }
}

When it happens

Trigger: Importing or requiring '@biomejs/runtime/plugin' (via import, require, or a bundler resolving it from a plugin entry) from code that is not being executed as a Biome JS plugin by the Biome plugin runtime.

Common situations: A developer writing a tool that should open/analyze files with Biome picks the wrong package name from autocomplete; a package rename or documentation confusion between 'runtime' (plugin-side runtime shipped with Biome plugins) and 'js-api' (embeddable API) causes a wrong import; copying an import from a Biome plugin repo into an ordinary Node script.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• empty file
• found a token with no parent

AI-assisted analysis of biomejs/biome@3835945f06 (2026-09-13). Data as JSON: /api/errors/a07120eafd76f78b. Report an issue: GitHub.