gatsbyjs/gatsby · critical · Error

'babel-plugin-styled-components' is not installed which is n

Error message

'babel-plugin-styled-components' is not installed which is needed by plugin 'gatsby-plugin-styled-components'

What it means

Thrown at plugin load time (gatsby-node.js top-level) by gatsby-plugin-styled-components when require.resolve('babel-plugin-styled-components') fails, meaning the peer dependency babel-plugin-styled-components is not installed in node_modules. The plugin needs the Babel plugin to transform styled-components at compile time.

Source

Thrown at packages/gatsby-plugin-styled-components/src/gatsby-node.js:5

// Add Babel plugin
try {
  require.resolve(`babel-plugin-styled-components`)
} catch (e) {
  throw new Error(
    `'babel-plugin-styled-components' is not installed which is needed by plugin 'gatsby-plugin-styled-components'`
  )
}

exports.pluginOptionsSchema = ({ Joi }) =>
  Joi.object({
    displayName: Joi.boolean()
      .default(true)
      .description(
        `This option enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. In your page source you'll see: <button class="Button-asdf123 asdf123" /> instead of just <button class="asdf123" />`
      ),
    fileName: Joi.boolean()
      .default(true)
      .description(`Prefix the displayName of a component with the filename.`),
    minify: Joi.boolean()
      .default(true)
      .description(`Remove the whitespace from the CSS.`),
    namespace: Joi.string()

View on GitHub (pinned to 8b06340921)

Solutions

1. Install the missing peer dependency: npm install babel-plugin-styled-components.
2. If using yarn workspaces or a monorepo, ensure babel-plugin-styled-components is resolvable from the package that uses the plugin.
3. Delete node_modules and lockfile, then reinstall to fix hoisting issues.
4. Verify styled-components itself is also installed as a dependency.

Example fix

# before: only gatsby-plugin-styled-components installed
npm install gatsby-plugin-styled-components
# after: install the peer dependency too
npm install gatsby-plugin-styled-components babel-plugin-styled-components styled-components

// Pre-build check for peer dependencies
const { execSync } = require('child_process')
try {
  execSync('require.resolve("babel-plugin-styled-components")', { stdio: 'pipe', cwd: process.cwd() })
} catch {
  console.error('Run: npm install babel-plugin-styled-components styled-components')
}

When it happens

Trigger: require.resolve() throws MODULE_NOT_FOUND when the package is absent; the catch converts it into this descriptive error. This happens the moment gatsby loads the plugin, before any build step.

Common situations: User installed gatsby-plugin-styled-components but forgot the peer dependency babel-plugin-styled-components, used npm install without --save, or has a monorepo where the dependency is hoisted incorrectly.

Related errors

• Couldn't check available APIs. Make sure you are on gatsby v
• BabelPluginRemoveGraphQLQueries: String interpolations are n
• BabelPluginRemoveGraphQLQueries: Unexpected empty graphql ta
• BabelPluginRemoveGraphQLQueries: GraphQL syntax error in que
• BabelPluginRemoveGraphQLQueries: the "${exportName}" export

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/204042cbfec34a17. Report an issue: GitHub.