[nextjs] Update the withPigment API to accept config

README.md

@@ -531,11 +531,9 @@ For example, in Next.js, you can define a theme in the `next.config.js` file lik
 ```js
 const { withPigment } = require('@pigment-css/nextjs-plugin');
 
-module.exports = withPigment(
-  {
-    // ...other nextConfig
-  },
-  {
+module.exports = withPigment({
+  // ...other nextConfig
+  pigment: {
     theme: {
       colors: {
         primary: 'tomato',
@@ -550,9 +548,12 @@ module.exports = withPigment(
       // ...more keys and values, it's free style!
     },
   },
-);
+});
 ```
 
+> [!NOTE]
+> The previous API to configure theming was to pass the data in the above `pigment` key as the second argument, ie, `withPigment(nextConfig, pigmentConfig)`. But it has been changed to follow what Next.js community follows.
+
 ### Accessing theme values
 
 A callback can be used with **styled()** and **css()** APIs to access the theme values:
@@ -572,11 +573,9 @@ Pigment CSS can generate CSS variables from the theme values when you wrap your
 ```js
 const { withPigment, extendTheme } = require('@pigment-css/nextjs-plugin');
 
-module.exports = withPigment(
-  {
-    // ...nextConfig
-  },
-  {
+module.exports = withPigment({
+  // ...nextConfig
+  pigment: {
     theme: extendTheme({
       colors: {
         primary: 'tomato',
@@ -590,7 +589,7 @@ module.exports = withPigment(
       },
     }),
   },
-);
+});
 ```
 
 The `extendTheme` utility goes through the theme and creates a `vars` object which represents the tokens that refer to CSS variables.
@@ -798,18 +797,23 @@ To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your
 ```js
 const { withPigment } = require('@pigment-css/nextjs-plugin');
 
-// ...
-module.exports = withPigment(nextConfig, {
-  theme: yourCustomTheme,
-  // CSS output option
-  css: {
-    // Specify your default CSS authoring direction
-    defaultDirection: 'ltr',
-    // Generate CSS for the opposite of the `defaultDirection`
-    // This is set to `false` by default
-    generateForBothDir: true,
+/** @type {import('@pigment-css/nextjs-plugin').WithPigmentOptions} */
+const nextConfig = {
+  pigment: {
+    theme: yourCustomTheme,
+    // CSS output option
+    css: {
+      // Specify your default CSS authoring direction
+      defaultDirection: 'ltr',
+      // Generate CSS for the opposite of the `defaultDirection`
+      // This is set to `false` by default
+      generateForBothDir: true,
+    },
   },
-});
+};
+
+// ...
+module.exports = withPigment(nextConfig);
 ```
 
 ### Vite
@@ -1136,12 +1140,12 @@ Next, they must set up Pigment CSS in their project:
 // framework config file, for example next.config.js
 const { withPigment } = require('@pigment-css/nextjs-plugin');
 
-module.exports = withPigment(
-  {
-    // ... Your nextjs config.
+module.exports = withPigment({
+  // ... Your nextjs config.
+  pigment: {
+    transformLibraries: ['your-package-name'],
   },
-  { transformLibraries: ['your-package-name'] },
-);
+});
 ```
 
 Finally, they must import the stylesheet in the root layout file:
@@ -1167,9 +1171,9 @@ Developers can customize the component's styles using the theme's `styleOverride
 For example, the custom theme below sets the background color of the statistics component's root slot to `tomato`:
 
 ```js
-module.exports = withPigment(
-  { ...nextConfig },
-  {
+module.exports = withPigment({
+  ...nextConfig,
+  pigment: {
     theme: {
       components: {
         PigmentStat: {
@@ -1188,15 +1192,15 @@ module.exports = withPigment(
       },
     },
   },
-);
+});
 ```
 
 Developers can also access theme values and apply styles based on the component's props using the `variants` key:
 
 ```js
-module.exports = withPigment(
-  { ...nextConfig },
-  {
+module.exports = withPigment({
+  ...nextConfig,
+  pigment: {
     theme: {
       // user defined colors
       colors: {
@@ -1229,7 +1233,7 @@ module.exports = withPigment(
       },
     },
   },
-);
+});
 ```
 
 ## How Pigment CSS works

apps/pigment-css-next-app/next.config.js → apps/pigment-css-next-app/next.config.mjs

@@ -1,7 +1,5 @@
-/* eslint-env node */
-// eslint-ignore-next-line import/no-unresolved
-const { withPigment } = require('@pigment-css/nextjs-plugin');
-const { extendTheme } = require('@mui/material/styles');
+import { withPigment } from '@pigment-css/nextjs-plugin';
+import { experimental_extendTheme as extendTheme } from '@mui/material';
 
 /**
  * @typedef {import('@pigment-css/nextjs-plugin').PigmentOptions} PigmentOptions
@@ -132,7 +130,7 @@ const pigmentOptions = {
   },
 };
 
-/** @type {import('next').NextConfig} */
+/** @type {import('@pigment-css/nextjs-plugin').WithPigmentOptions} */
 const nextConfig = {
   eslint: {
     ignoreDuringBuilds: true,
@@ -144,6 +142,7 @@ const nextConfig = {
     buildActivity: true,
     buildActivityPosition: 'bottom-right',
   },
+  pigment: pigmentOptions,
 };
 
-module.exports = withPigment(nextConfig, pigmentOptions);
+export default withPigment(nextConfig);

apps/pigment-css-next-app/package.json

@@ -2,6 +2,7 @@
   "name": "@app/next-app",
   "version": "0.1.0",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "next dev",
     "build": "next build",

examples/pigment-css-nextjs-ts/next.config.js → examples/pigment-css-nextjs-ts/next.config.mjs

@@ -1,4 +1,4 @@
-const { withPigment, extendTheme } = require('@pigment-css/nextjs-plugin');
+import { withPigment, extendTheme } from '@pigment-css/nextjs-plugin';
 
 // To learn more about theming, visit https://github.com/mui/pigment-css/blob/master/README.md#theming
 const theme = extendTheme({
@@ -22,7 +22,11 @@ const theme = extendTheme({
   },
 });
 
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
+/** @type {import('@pigment-css/nextjs-plugin').WithPigmentOptions} */
+const nextConfig = {
+  pigment: {
+    theme,
+  },
+};
 
-module.exports = withPigment(nextConfig, { theme });
+module.exports = withPigment(nextConfig);

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

@@ -3,15 +3,25 @@ import type { NextConfig } from 'next';
 import { findPagesDir } from 'next/dist/lib/find-pages-dir';
 import { webpack as webpackPlugin, extendTheme, type PigmentOptions } from '@pigment-css/unplugin';
 
-export { type PigmentOptions };
+export interface WithPigmentOptions extends NextConfig {
+  pigment?: PigmentOptions;
+}
 
 const extractionFile = path.join(
   path.dirname(require.resolve('../package.json')),
   'zero-virtual.css',
 );
 
-export function withPigment(nextConfig: NextConfig, pigmentConfig?: PigmentOptions) {
-  const { babelOptions = {}, asyncResolve, ...rest } = pigmentConfig ?? {};
+export function withPigment(
+  { pigment, ...nextConfig }: WithPigmentOptions,
+  pigmentConfig?: PigmentOptions,
+) {
+  const { babelOptions = {}, asyncResolve, ...rest } = pigment ?? pigmentConfig ?? {};
+  if (pigmentConfig) {
+    console.warn(
+      'Passing Pigment CSS config through the 2nd argument is deprecated and will be removed in a future stable version. Instead, pass the config through the `pigment` key in your next.js config.',
+    );
+  }
   if (process.env.TURBOPACK === '1') {
     // eslint-disable-next-line no-console
     console.log(
@@ -103,4 +113,4 @@ export function withPigment(nextConfig: NextConfig, pigmentConfig?: PigmentOptio
   };
 }
 
-export { extendTheme };
+export { extendTheme, type PigmentOptions };