withastro/astro · error · Error

Invalid package name

Error message

Invalid package name "${packageName}". Package names must follow npm naming rules: lowercase letters, numbers, hyphens, underscores, and dots. Scoped packages like @org/package are also supported.

What it means

`assertValidPackageName` in @astrojs/internal-helpers validates that a string is a legal npm package name before it is passed to package-manager commands. It is a command-injection and typo guard: names like `react; whoami` would otherwise be forwarded to spawned npm/pnpm/bun commands. The message enumerates the accepted shape (lowercase letters, numbers, hyphens, underscores, dots, and @scope/name).

Solutions

Pass a plain, lowercase npm package name: `astro add react`
For scoped integrations use `astro add @astrojs/sitemap`
If you need a specific version, add it afterwards with your package manager (`npm i astro@5.0.0`), not via `astro add`
If the name comes from user input in a script, validate it first with the same npm naming rules

Example fix

# before
astro add "tailwind@4"

# after
astro add tailwind
npx astro tailwind add  # then manage versions via the package manager

Defensive patterns

Strategy: validation

Validate before calling

import validatePackageName from 'validate-npm-package-name';
function safePkgName(input: string): string | null {
  return validatePackageName(input).validForNewPackages ? input : null;
}

Type guard

function isValidNpmName(name: string): boolean {
  return /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
}

Prevention

Never interpolate untrusted shell input into `astro add`
Pass plain lowercase npm names; handle versions with the package manager itself
In scripts wrapping astro add, validate names first with validate-npm-package-name

When it happens

Trigger: Running `astro add "react; rm -rf ~"` or any argument with spaces/semicolons; passing an uppercase name (`astro add React`); appending a version (`astro add react@19`) if the validator rejects the `@version` suffix; passing an empty or malformed scoped name like `@/pkg`.

Common situations: Shell scripts or CI pipelines interpolating untrusted strings into `astro add`; users assuming `astro add` accepts version specifiers like `npm install` does; copy-pasting package names with stray whitespace or quotes.

Related errors

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

Appendix: source

Thrown at packages/internal-helpers/src/cli.ts:43

export function validatePackageName(packageName: string): boolean {
	return NPM_PACKAGE_NAME_REGEX.test(packageName);
}

/**
 * Validates a package name and throws an error if invalid.
 *
 * @param packageName - The package name to validate
 * @throws {Error} If the package name is invalid
 *
 * @example
 * ```ts
 * assertValidPackageName('react'); // OK
 * assertValidPackageName('react; whoami'); // throws Error
 * ```
 */
export function assertValidPackageName(packageName: string): asserts packageName is string {
	if (!validatePackageName(packageName)) {
		throw new Error(
			`Invalid package name "${packageName}". Package names must follow npm naming rules: ` +
				`lowercase letters, numbers, hyphens, underscores, and dots. ` +
				`Scoped packages like @org/package are also supported.`,
		);
	}
}

View on GitHub (pinned to 52e6c34790)