parcel-bundler/parcel · error · Error

PostCSS config should be an object.

Error message

PostCSS config should be an object.

What it means

Thrown by @parcel/transformer-postcss's config loader when the parsed PostCSS config file is not a plain object (typeof contents !== 'object'). This typically means a JS config that exports a non-object (string, number, array, null after JSON parse, or a function/class in JS configs that Parcel evaluates to a non-object).

Source

Thrown at packages/transformers/postcss/src/loadConfig.js:196

      specifier: 'postcss',
      resolveFrom: config.searchPath,
      range: POSTCSS_RANGE,
    });

    contents = configFile.contents;
    let isDynamic =
      configFile && path.extname(configFile.filePath).endsWith('js');
    if (isDynamic) {
      // We have to invalidate on startup in case the config is non-deterministic,
      // e.g. using unknown environment variables, reading from the filesystem, etc.
      logger.warn({
        message:
          'WARNING: Using a JavaScript PostCSS config file means losing out on caching features of Parcel. Use a .postcssrc(.json) file whenever possible.',
      });
    }

    if (typeof contents !== 'object') {
      throw new Error('PostCSS config should be an object.');
    }

    if (
      contents.plugins == null ||
      typeof contents.plugins !== 'object' ||
      Object.keys(contents.plugins).length === 0
    ) {
      throw new Error('PostCSS config must have plugins');
    }
  }

  return configHydrator(
    contents,
    config,
    configFile?.filePath,
    options,
    logger,
  );

View on GitHub (pinned to 59484858a1)

Solutions

1. Open the named PostCSS config file and ensure it exports an object literal `{ ... }`.
2. For JS configs, double check `module.exports = { ... }` (CommonJS) or the equivalent default export.
3. For JSON configs, make sure the top-level value is `{ }`, not an array or scalar.
4. If the config is dynamic/conditional, ensure every code path returns an object.

Example fix

// before: postcss.config.js
module.exports = 'tailwindcss';
// after
module.exports = {
  plugins: {
    tailwindcss: {}
  }
};

function assertPostCSSConfigShape(contents) {
  if (typeof contents !== 'object' || contents === null || Array.isArray(contents)) {
    throw new Error('PostCSS config must be a plain object');
  }
}

function isPostCSSConfigObject(contents) {
  return contents !== null && typeof contents === 'object' && !Array.isArray(contents);
}

When it happens

Trigger: A PostCSS config (`.postcssrc`, `.postcssrc.json`, `.postcssrc.js`, `postcss.config.js`, or the `postcss` key in package.json) whose evaluated value fails the `typeof === 'object'` check. Examples: postcss.config.js with `module.exports = 'tailwind'`, a JSON file containing an array, or a JS file that conditionally returns null.

Common situations: Hand-editing postcss.config.js and forgetting the object literal; copy-pasting a config snippet that exports a string; using CommonJS in an ESM project so `module.exports` evaluates to undefined and gets coerced; malformed `.postcssrc.json` that is a JSON array.

Related errors

• PostCSS config must have plugins
• The 'elm.json' file is missing.
• failed to locate file ${originalPath}
• Unsupported SVGR option "jsx".
• Unsupported SVGR option "template".

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/d2ec18969dc1ab6c. Report an issue: GitHub.