Suppress warnings in webpack

Also add descriptions for each bundler option and don't expose internal
options to user.

Author: Brijesh Bittu

packages/pigment-css-plugin/src/nextjs.ts

@@ -3,6 +3,7 @@ import type { NextConfig } from 'next';
 import { findPagesDir } from 'next/dist/lib/find-pages-dir';
 
 import webpackPlugin from './webpack';
+import type { ExcludePluginOptions } from './utils';
 
 const NEXTJS_ARTIFACTS = 'nextjs-artifacts';
 
@@ -12,10 +13,7 @@ const extractionFile = path.join(
   'pigment-virtual.css',
 );
 
-export type PigmentCSSConfig = Exclude<
-  Parameters<typeof webpackPlugin>[0],
-  'createResolver' | 'postTransform'
->;
+export type PigmentCSSConfig = Exclude<Parameters<typeof webpackPlugin>[0], ExcludePluginOptions>;
 
 export default function pigment(
   nextConfig: NextConfig,
@@ -101,13 +99,12 @@ export default function pigment(
       }),
     );
 
+    config.ignoreWarnings = config.ignoreWarnings ?? [];
+    config.ignoreWarnings.push((warning: string) => warning.includes('pigment-virtual'));
+
     if (typeof nextConfig.webpack === 'function') {
       return nextConfig.webpack(config, context);
     }
-    config.ignoreWarnings = config.ignoreWarnings ?? [];
-    config.ignoreWarnings.push({
-      module: /(pigment-virtual\.css)|(core\/styles\.css)|(react\/styles\.css)/,
-    });
     return config;
   };
   return {

packages/pigment-css-plugin/src/unplugin.ts

@@ -23,11 +23,31 @@ import { logger as wywLogger } from '@wyw-in-js/shared';
 import { AsyncResolver, handleUrlReplacement } from './utils';
 
 type BundlerConfig = Omit<PigmentConfig, 'themeArgs'> & {
+  /**
+   * Extra filter to only allow files that satisfy this pattern
+   */
   include?: FilterPattern;
+  /**
+   * Extra filter to not transform files that satisfy this pattern.
+   */
   exclude?: FilterPattern;
+  /**
+   * The Theme object that'll be passed to the callback in the css or styled calls.
+   */
   theme?: Theme;
+  /**
+   * A list of package names that support the runtime implementation of Pigment CSS. This already includes
+   * `@pigment-css/core`, `@pigment-css/react` and `@pigment-css/react-new`.
+   */
   runtimePackages?: string[];
-  corePackages?: string[];
+  /**
+   * Extra package names that should always be transformed regardless of the `include` and `exclude` patterns.
+   */
+  transformPackages?: string[];
+  /**
+   * If you want to support `sx` prop in your application, set this to true.
+   * @default false
+   */
   transformSx?: boolean;
   nextJsOptions?: {
     dev: boolean;
@@ -37,6 +57,9 @@ type BundlerConfig = Omit<PigmentConfig, 'themeArgs'> & {
   };
   outputCss?: boolean;
   debug?: IFileReporterOptions | false;
+  /**
+   * Enable sourceMap for the generated css.
+   */
   sourceMap?: boolean;
   asyncResolve?: AsyncResolver;
   createResolver?: (ctx: any, projectPath: string, config?: any) => AsyncResolver;
@@ -141,7 +164,7 @@ export const plugin = createUnplugin<BundlerConfig>((options, meta) => {
   const {
     outputCss = true,
     theme = {},
-    corePackages = [],
+    transformPackages = [],
     runtimePackages: optRuntimePackages = [],
     debug = false,
     transformSx = true,
@@ -240,7 +263,7 @@ export const plugin = createUnplugin<BundlerConfig>((options, meta) => {
     plugins.push(
       getSxBabelUnplugin({
         name: `${baseName}/sx`,
-        finalTransformLibraries: corePackages,
+        finalTransformLibraries: transformPackages,
         filter,
       }),
     );
@@ -262,7 +285,7 @@ export const plugin = createUnplugin<BundlerConfig>((options, meta) => {
       },
     },
     transformInclude(id) {
-      return isZeroRuntimeProcessableFile(id.split('?', 1)[0], corePackages) && filter(id);
+      return isZeroRuntimeProcessableFile(id.split('?', 1)[0], transformPackages) && filter(id);
     },
     async transform(code, url) {
       const [filePath] = url.split('?', 1);

packages/pigment-css-plugin/src/utils.ts

@@ -6,6 +6,8 @@ export type AsyncResolver = (
   stack: string[],
 ) => Promise<string | null>;
 
+export type ExcludePluginOptions = 'createResolver' | 'postTransform' | 'nextJsOptions';
+
 /**
  * There might be a better way to do this in future, but due to the async
  * nature of the resolver, this is the best way currently to replace url()

packages/pigment-css-plugin/src/vite.ts

@@ -4,11 +4,11 @@ import { optimizeDeps } from 'vite';
 import { syncResolve } from '@wyw-in-js/shared';
 
 import { plugin } from './unplugin';
-import { AsyncResolver } from './utils';
+import type { AsyncResolver, ExcludePluginOptions } from './utils';
 
 export type PigmentCSSConfig = Exclude<
   Parameters<(typeof plugin)['vite']>[0],
-  'createResolver' | 'postTransform'
+  ExcludePluginOptions
 >;
 
 export default function pigment(config: Parameters<(typeof plugin)['vite']>[0]) {

packages/pigment-css-plugin/src/webpack.ts

@@ -1,20 +1,20 @@
 import * as path from 'node:path';
 
-import { NativeBuildContext } from 'unplugin';
+import type { NativeBuildContext } from 'unplugin';
 
 import { plugin } from './unplugin';
-import { AsyncResolver } from './utils';
+import type { AsyncResolver, ExcludePluginOptions } from './utils';
 
 export type PigmentCSSConfig = Exclude<
   Parameters<(typeof plugin)['webpack']>[0],
-  'createResolver' | 'postTransform'
+  ExcludePluginOptions
 >;
 
 export default function pigment(config: Parameters<(typeof plugin)['webpack']>[0]) {
   function createResolver(ctx: NativeBuildContext, projectPath: string): AsyncResolver {
     return async (what, importer) => {
       if (ctx.framework !== 'webpack') {
-        throw new Error('Non-webpack bundlers not supported');
+        throw new Error(`${process.env.PACKAGE_NAME}: Non-webpack bundlers are not supported`);
       }
 
       const context = path.isAbsolute(importer)