Throw an error when mixing extract: true and classHashPrefix conf…

…iguration options to avoid unsupported usage and bundle size bloat. (#1724)

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

* Update docs

* Add changesets and finalize docs

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

Co-authored-by: Grant Wong <2908767+dddlr@users.noreply.github.com>

* Add changesets and finalize docs

* feat: add classHashPrefix to webpack loader

* docs: update webpack-loader docs

* chore: add changeset for fix

---------

Co-authored-by: Grant Wong <2908767+dddlr@users.noreply.github.com>
Co-authored-by: Guilherme Oliveira <goliveira@atlassian.com>

.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/seven-beers-shake.md

@@ -0,0 +1,5 @@
+---
+'@compiled/webpack-loader': patch
+---
+
+fix: webpack loader wasn't passing classHashPrefix option down to babel plugin

.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/compiled-loader.ts

@@ -40,6 +40,7 @@ function getLoaderOptions(context: LoaderContext<CompiledLoaderOptions>) {
     extractStylesToDirectory = undefined,
     resolver = undefined,
     importSources = undefined,
+    classHashPrefix = undefined,
   }: CompiledLoaderOptions = typeof context.getOptions === 'undefined'
     ? // Webpack v4 flow
       getOptions(context)
@@ -95,6 +96,9 @@ function getLoaderOptions(context: LoaderContext<CompiledLoaderOptions>) {
           importSources: {
             type: 'array',
           },
+          classHashPrefix: {
+            type: 'string',
+          },
         },
       });
 
@@ -115,6 +119,7 @@ function getLoaderOptions(context: LoaderContext<CompiledLoaderOptions>) {
     extractStylesToDirectory,
     resolver,
     importSources,
+    classHashPrefix,
   };
 }
 

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

@@ -103,6 +103,15 @@ export interface CompiledLoaderOptions {
    * Passed to @compiled/babel-plugin.
    */
   importSources?: string[];
+
+  /**
+   * 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;
 }
 
 export interface CompiledExtractPluginOptions {
@@ -142,10 +151,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]*$`.