Astro "Cannot use import statement outside a module" in CI

By Kaveh Alemi·Latchkey

This SyntaxError comes from Node when ESM import syntax is evaluated in a CommonJS context. In an Astro project it usually means a dependency ships ESM-only code loaded as CJS, or a config/entry is treated as CommonJS while using import.

What this error means

The build or a Node step fails with "SyntaxError: Cannot use import statement outside a module", pointing at a dependency file or a config.

import { defineConfig } from 'astro/config';
^^^^^^
SyntaxError: Cannot use import statement outside a module
    at internalCompileFunction (node:internal/vm)

Common causes

An ESM-only dependency loaded as CommonJS

A package ships only ESM but is required from a CJS context, so Node parses import where it is not allowed.

A config or entry not treated as a module

A .js file using import without "type": "module" (or the right extension) is parsed as CommonJS.

How to fix it

Declare the project as ESM

1. Set "type": "module" in package.json, or use the .mjs extension for ESM configs.
2. Ensure Node is a version that supports the ESM the deps require.
3. Re-run the build.

// package.json
{ "type": "module" }

Let Vite bundle the ESM dependency

For an ESM-only dep that a server context loads as CJS, add it to ssr.noExternal so Vite bundles it.

// astro.config.mjs
export default { vite: { ssr: { noExternal: ["esm-only-lib"] } } };

How to prevent it

• Use "type": "module" or .mjs for ESM configs.
• Keep the runner Node version current for ESM support.
• Bundle ESM-only deps via ssr.noExternal when needed.

Frequently asked questions

Related guides

References

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