withastro/astro · error · Error

doesn't appear to be an integration or an adapter. Find our…

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

`astro add` successfully fetched the package.json but its `keywords` array contains neither `astro-integration` nor `astro-adapter`. Keywords are the machine-readable marker Astro uses to distinguish real integrations/adapters from arbitrary npm packages, so it refuses to install and wire up anything unmarked.

Solutions

1. If the package is not an integration/adapter, install it with your package manager directly (`npm i <pkg>`) instead of `astro add`
2. If it IS a real integration missing keywords, install it manually and register it in astro.config yourself, or ask the author/PR to add `"astro-integration"` (or `"astro-adapter"`) to package.json keywords
3. If you are the author, publish with the correct keywords so `astro add` accepts the package

Example fix

// before — package.json of the community integration
"keywords": ["astro", "markdown"]

// after
"keywords": ["astro", "astro-integration", "markdown"]

import { execSync } from 'node:child_process';

function isAstroIntegration(spec) {
  try {
    const keywords = JSON.parse(
      execSync(`npm view ${spec} keywords --json`, { stdio: ['pipe', 'pipe', 'ignore'] }).toString(),
    );
    return (
      Array.isArray(keywords) &&
      (keywords.includes('astro-integration') || keywords.includes('astro-adapter'))
    );
  } catch {
    return false;
  }
}

if (!isAstroIntegration(spec)) {
  // install as a normal dependency instead of `astro add`
}

function isAddableIntegration(pkgJson) {
  const keywords = Array.isArray(pkgJson?.keywords) ? pkgJson.keywords : [];
  return keywords.includes('astro-integration') || keywords.includes('astro-adapter');
}

When it happens

Trigger: `astro add <non-integration-package>` (any npm package without the keywords); adding a community integration whose author forgot `"astro-integration"` or `"astro-adapter"` in package.json; adding a package that is a plain library even though it is Astro-related.

Common situations: Expecting `astro add` to work for any npm package; third-party integration authors omitting keywords; testing your own unpublished integration locally without the keywords set.

Related errors

• No problem! Find our official integrations at…
• Unable to fetch . Does the package exist?
• Couldn't parse tsconfig.json or jsconfig.json
• Invalid package name
• The adapter doesn't provide a feature map. It is required…

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

Appendix: source

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

				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 e294953aa8)