[nextjs] Update the withPigment API to accept config

through `pigment` key from the nextConfig object itself instead of as a
2nd argument to the call. This is a standard approach followed by other
nextjs plugins

Fixes: mui#83

Author: brijeshb42

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

@@ -106,7 +106,7 @@ const pigmentOptions = {
   displayName: true,
 };
 
-/** @type {import('next').NextConfig} */
+/** @type {import('@pigment-css/nextjs-plugin').WithPigmentOptions} */
 const nextConfig = {
   eslint: {
     ignoreDuringBuilds: true,
@@ -118,6 +118,7 @@ const nextConfig = {
     buildActivity: true,
     buildActivityPosition: 'bottom-right',
   },
+  pigment: pigmentOptions,
 };
 
-module.exports = withPigment(nextConfig, pigmentOptions);
+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 };