Astro "Cannot find package" integration resolution error in CI

By Daniel Zoghalchali·Latchkey

When Astro loads astro.config.mjs, Node resolves each imported integration from node_modules. If a package is referenced but not installed, Node throws "Cannot find package" before the build starts.

What this error means

astro build fails at config load with "Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@astrojs/react' imported from astro.config.mjs". It works locally where the package exists.

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@astrojs/react' imported from
/app/astro.config.mjs
    at packageResolve (node:internal/modules/esm/resolve)

Common causes

The integration is not in package.json

The config imports an integration that was installed locally but never saved as a dependency, so npm ci skips it.

A peer framework package is missing

An integration such as @astrojs/react needs react and react-dom; if those are absent the resolution still fails.

How to fix it

Install the package as a real dependency

1. Add the named package (and its framework peers) to package.json.
2. Run npm ci so the clean install matches CI.
3. Re-run the build to confirm config loads.

npx astro add react
npm ci

Commit the lockfile change

Ensure the new dependency and lockfile are committed so CI installs them.

git add package.json package-lock.json
git commit -m "add astro react integration"

How to prevent it

• Use astro add so integrations are saved to package.json.
• Commit lockfile changes with the config change.
• Run a clean npm ci build locally to catch missing packages.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation