withastro/astro · error · Error

${packageName} doesn't appear to be an integration or an ada

Error message

${packageName} doesn't appear to be an integration or an adapter. Find our official integrations at https://astro.build/integrations

What it means

After fetching a package's package.json, `astro add` decides whether it is an integration or an adapter by checking its `keywords` for 'astro-integration' or 'astro-adapter'. If neither keyword is present, it throws this Error pointing the user to the integrations page. The package exists on npm but is not labeled as Astro-compatible.

Source

Thrown at packages/astro/src/cli/add/index.ts:922

				if (pkgJson['peerDependencies']) {
					const meta = pkgJson['peerDependenciesMeta'] || {};
					for (const peer in pkgJson['peerDependencies']) {
						const optional = meta[peer]?.optional || false;
						const isAstro = peer === 'astro';
						if (!optional && !isAstro) {
							dependencies.push([peer, pkgJson['peerDependencies'][peer]]);
						}
					}
				}

				let integrationType: IntegrationInfo['type'];
				const keywords = Array.isArray(pkgJson['keywords']) ? pkgJson['keywords'] : [];
				if (keywords.includes('astro-integration')) {
					integrationType = 'integration';
				} else if (keywords.includes('astro-adapter')) {
					integrationType = 'adapter';
				} else {
					throw new Error(
						`${bold(
							packageName,
						)} doesn't appear to be an integration or an adapter. Find our official integrations at ${cyan(
							'https://astro.build/integrations',
						)}`,
					);
				}

				if (integration === 'tailwind') {
					integrationName = 'tailwind';
					dependencies = [
						['@tailwindcss/vite', '^4.0.0'],
						['tailwindcss', '^4.0.0'],
					];
				}
				return {
					id: integration,
					packageName,

View on GitHub (pinned to d081033d5f)

Solutions

1. Confirm the package is meant for Astro; if so, ask its maintainer to add `astro-integration` (or `astro-adapter`) to package.json keywords.
2. Find the correct official/community integration at https://astro.build/integrations and use that name.
3. If the package is valid but unlabeled, install it manually (`pnpm add <pkg>`) and add it to integrations in astro.config.mjs yourself.
4. Double-check for a typo that resolved to a different, non-Astro package.

Example fix

# before — real npm package, no astro keyword
astro add some-random-utils

# after — install manually and register
pnpm add some-random-utils
// astro.config.mjs
import somePlugin from 'some-random-utils';
export default defineConfig({ integrations: [somePlugin()] });

async function hasAstroKeyword(name: string, tag = 'latest') {
  const r = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/${tag}`);
  if (!r.ok) return false;
  const pkg = await r.json();
  const kw: string[] = Array.isArray(pkg.keywords) ? pkg.keywords : [];
  return kw.includes('astro-integration') || kw.includes('astro-adapter');
}

function isAstroIntegrationPkg(pkg: { keywords?: unknown }): boolean {
  return Array.isArray(pkg.keywords) && (pkg.keywords.includes('astro-integration') || pkg.keywords.includes('astro-adapter'));
}

When it happens

Trigger: Running `astro add <pkg>` for a real npm package whose package.json lacks both `astro-integration` and `astro-adapter` in its keywords array. Common with unrelated packages that happen to share a name, or community packages that forgot the keyword.

Common situations: A community integration that did not add `astro-integration` to its keywords; passing a plain utility library by mistake; package name collision with a non-Astro package; the integration is set up via a different install method.

Related errors

• ${integration} does not appear to be a valid package name!
• Unable to fetch ${integration}. Does the package exist?
• Unknown error parsing tsconfig.json or jsconfig.json. Could
• No problem! Find our official integrations at https://astro.
• ${key} expects a "${defaultType}" value!

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/9b84e98df9d16961. Report an issue: GitHub.