#When Astro config Vite SSR noExternals is defined, then dev mode breaks

1 messages · Page 1 of 1 (latest)

hardy mist
#

IN the astro config file I have Vite SSR noExternals defined for React and other modules.
When locally running astro dev, it tells me "module is not defined" and breaks on React.
How can I prevent this?

manic ruinBOT
#

Hi @hardy mist. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

When you define vite.ssr.noExternal in your Astro config for React and other modules, it tells Vite not to externalize those packages during server-side rendering. This is sometimes necessary for certain packages, but it can also cause issues if used incorrectly—especially in development mode.

The error “module is not defined” for React usually means that React (or another dependency) is not being bundled or resolved correctly, possibly due to how noExternal is set up. Here are some things to check and try:

  1. Ensure React and React-DOM are installed
    If you see errors about React not being found, make sure both react and react-dom are installed in your project. Astro integrations like @astrojs/react require these as peer dependencies. Install them with:

    npm install react react-dom

    See troubleshooting guide

  2. Check your vite.ssr.noExternal usage
    The noExternal option should only include packages that need to be bundled by Vite for SSR. Overusing it (e.g., including react and react-dom without a specific reason) can cause issues, especially in dev mode.
    Example:

    export default defineConfig({
  vite: {
    ssr: {
      noExternal: ['@astrojs/react'] // Only add what's necessary
    }
  }
})

    See configuration reference

  3. Monorepo setups
    If you’re in a monorepo, you may need to add Astro-related dependencies to vite.ssr.noExternal to ensure proper bundling, but this is typically for integrations, not for React itself unless you have a specific reason.
    See monorepo troubleshooting

#

  1. Don’t add React to noExternal unless required
    Normally, you do not need to add react or react-dom to noExternal. Only do this if a specific error or integration requires it. If you remove them from noExternal, your dev mode should work as expected.

  2. If you’re using Preact with compat
    If you’re swapping React for Preact using preact/compat, you may need to add certain libraries to noExternal, but again, not React itself unless the library is ESM-only and you see a build-time error.
    See Preact integration guide

Summary:
Remove react and react-dom from your vite.ssr.noExternal array unless you have a specific, documented reason to include them. This should resolve the “module is not defined” error in dev mode. Only add packages to noExternal if the documentation or an error message specifically instructs you to do so.

If you continue to have issues, double-check your package installations and your import paths, as missing or misconfigured dependencies can also cause similar errors.

If you need to import a CSS file from a package without a file extension, then you should add that package to noExternal, but this is not required for React itself unless you have a special case see styling guide.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@hardy mist Kapa.ai is still learning and improving, please let me know how I did by reacting below.

hardy mist
#

if I remove react from noExternal then the build breaks. Can I make the SSR prop to be ignored in dev mode?

#

@manic ruin if I remove react from noExternal then the build breaks. Can I make the SSR prop to be ignored in dev mode?

manic ruinBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Astro’s configuration does not provide a built-in way to conditionally apply vite.ssr.noExternal only in build mode and ignore it in dev mode directly within the config file. The vite.ssr.noExternal array is applied as part of the Vite configuration, and Astro merges this config for both dev and build unless you programmatically adjust it.

However, you can programmatically modify your Astro config to set vite.ssr.noExternal only when building, by checking the current command or environment. For example, you can use process.env.NODE_ENV or similar logic in your astro.config.mjs:

import { defineConfig } from 'astro/config';

const isBuild = process.env.NODE_ENV === 'production';

export default defineConfig({
  vite: {
    ssr: {
      noExternal: isBuild ? ['react'] : [],
    }
  }
});

But please note: the official Astro documentation does not explicitly mention this pattern or guarantee that it will work in all cases. The knowledge sources do not provide a documented, built-in option to ignore vite.ssr.noExternal in dev mode only. If you need more advanced conditional logic, you may need to use integration hooks or custom scripts, but this is not covered in the provided documentation.

Summary:
There is no officially documented way in Astro to have vite.ssr.noExternal only apply in build mode and be ignored in dev mode. Any such solution would be a workaround and not guaranteed by the current documentation. If you continue to encounter issues, you may want to review your dependencies or seek further support from the Astro community.

See Vite configuration in Astro

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: