Throw an error when mixing extract: true and classHashPrefix configuration options to avoid unsupported usage and bundle size bloat.

.changeset/fluffy-cherries-exercise.md

@@ -0,0 +1,7 @@
+---
+'@compiled/parcel-transformer': patch
+'@compiled/webpack-loader': patch
+'@compiled/babel-plugin': patch
+---
+
+Documents what happens when mixing extraction and classHashPrefix

.changeset/silver-jokes-care.md

@@ -0,0 +1,6 @@
+---
+'@compiled/parcel-transformer': minor
+'@compiled/webpack-loader': minor
+---
+
+Throw an error when mixing `extract: true` and `classHashPrefix` configuration options to avoid unsupported usage and bundle size bloat.

packages/babel-plugin/src/types.ts

@@ -107,6 +107,9 @@ export interface PluginOptions {
  /**
  * Adds a defined prefix to the generated classes' hashes.
  * Useful in micro frontend environments to avoid clashing/specificity issues.
+ *
+ * Avoid mixing this with extraction as this may throw an error if combined with extraction
+ * or `extract: true` in Webpack loaders or Parcel tranformers.
  */
  classHashPrefix?: string;
 }

packages/parcel-transformer/src/index.ts

@@ -124,6 +124,12 @@ export default new Transformer<ParcelTransformerOpts>({
  },
 
  async transform({ asset, config, options }) {
+ if (config.extract && config.classHashPrefix) {
+ throw new Error(
+ '`@compiled/parcel-transformer` is mixing `extract: true` and `classHashPrefix` options, which will not supported and will result in bundle size bloat.'
+ );
+ }
+
  const ast = await asset.getAST();
 
  if (!(ast?.type === 'babel' && ast.program)) {

packages/parcel-transformer/src/types.ts

@@ -71,6 +71,8 @@ export interface ParcelTransformerOpts extends BabelPluginOpts {
  /**
  * Adds a defined prefix to the generated classes' hashes.
  * Useful in micro frontend environments to avoid clashing/specificity issues.
+ *
+ * This will throw an error if used alongside extraction or `extract: true`.
  */
  classHashPrefix?: string;
 }

packages/webpack-loader/src/extract-plugin.ts

@@ -108,6 +108,13 @@ export class CompiledExtractPlugin {
 
  constructor(options: CompiledExtractPluginOptions = {}) {
  this.#options = options;
+
+ // @ts-expect-error -- Make sure this config doesn't bleed in as it's passed through
+ if (options.classHashPrefix) {
+ throw new Error(
+ '`@compiled/webpack-loader.CompiledExtractPlugin` is mixing the `extract: true` and `classHashPrefix` options, which is not supported and will result in bundle size bloat.'
+ );
+ }
  }
 
  apply(compiler: Compiler): void {

packages/webpack-loader/src/types.ts

@@ -142,10 +142,4 @@ export interface CompiledExtractPluginOptions {
  * Defaults to `false`.
  */
  sortShorthand?: boolean;
-
- /**
- * Adds a defined prefix to the generated classes' hashes.
- * Useful in micro frontend environments to avoid clashing/specificity issues.
- */
- classHashPrefix?: string;
 }

website/packages/docs/src/pages/pkg-babel-plugin.mdx

@@ -83,7 +83,7 @@ Will cache the result of statically evaluated imports.
 
 Adds a prefix to the generated hashed css rule names. The valued passed to it gets hashed in conjunction with the rest of the rule declaration.
 
-This is useful when `@compiled` is being used in a micro frontend environment by multiple packages and you want to avoid specificity issues.
+This is useful when `@compiled` is being used in a micro frontend environment by multiple packages and you want to avoid specificity issues. Please note that mixing this with extraction is not supported and Parcel or Webpack will throw an error if combined.
 
 The currently accepted regex for this value is `^[a-zA-Z\-_]+[a-zA-Z\-_0-9]*$`.
 

website/packages/docs/src/pages/pkg-webpack-loader.mdx

@@ -211,7 +211,6 @@ module.exports = {
 `@compiled/webpack-loader` also accepts the following options. These are not used in the loader itself, but instead they are passed directly to the underlying `@compiled/babel-plugin`.
 
 - `addComponentName`
-- `classHashPrefix`
 - `classNameCompressionMap`
 - `importReact`
 - `importSources`