Improve CHANGELOG, enhance missing PostCSS config error message with examples for ESM and CJS formats

Author: Kocal

CHANGELOG.md

@@ -39,6 +39,51 @@ can adopt modern async APIs from the ecosystem without hacks**.
   Note: `Encore.getWebpackConfig()` is now **async** and returns a `Promise`. Use `await` at the
   top level of your webpack config (webpack supports async config files natively).
 
+* If you prefer not to add `"type": "module"` to your project, you can rename your webpack config
+  file to `webpack.config.mjs` instead. Webpack detects the `.mjs` extension and treats it as ESM
+  automatically — no other changes needed.
+
+* Replace `__dirname` and `__filename` with their ESM equivalents in your webpack config:
+  ```js
+  // Before (CJS)
+  path.resolve(__dirname, 'src/utilities/')
+  config: [__filename]
+
+  // After (ESM)
+  path.resolve(import.meta.dirname, 'src/utilities/')
+  config: [import.meta.filename]
+  ```
+
+* Replace `require()` calls in your webpack config with `import` statements:
+  ```js
+  // Before (CJS)
+  const path = require('path');
+
+  // After (ESM)
+  import path from 'path';
+  ```
+  If you need to require a CJS-only package, use `createRequire`:
+  ```js
+  import { createRequire } from 'module';
+  const require = createRequire(import.meta.url);
+  const somePackage = require('cjs-only-package');
+  ```
+
+* Config files that use CJS syntax (`module.exports`, `require()`) must be renamed to `.cjs` if
+  your project has `"type": "module"` in its `package.json`. This affects files such as:
+  - `postcss.config.js` → `postcss.config.cjs`
+  - `babel.config.js` → `babel.config.cjs`
+
+  Alternatively, rewrite them as ESM:
+  ```js
+  // postcss.config.js (ESM)
+  export default {
+      plugins: {
+          autoprefixer: {},
+      },
+  };
+  ```
+
 * The package `"exports"` field is now restrictive: only `"@symfony/webpack-encore"` and
   `"@symfony/webpack-encore/lib/plugins/plugin-priorities.js"` are exposed as public entry points.
   If you were importing other internal modules directly, those imports will no longer work.

index.js

@@ -377,8 +377,8 @@ class Encore {
      *
      * ```
      * Encore.addAliases({
-     *     Utilities: path.resolve(__dirname, 'src/utilities/'),
-     *     Templates: path.resolve(__dirname, 'src/templates/')
+     *     Utilities: path.resolve(import.meta.dirname, 'src/utilities/'),
+     *     Templates: path.resolve(import.meta.dirname, 'src/templates/')
      * })
      * ```
      *
@@ -1052,12 +1052,12 @@ class Encore {
      * Encore.enableBuildCache({
      *     // object of "buildDependencies"
      *     // https://webpack.js.org/configuration/other-options/#cachebuilddependencies
-     *     // __filename means that changes to webpack.config.js should invalidate the cache
-     *     config: [__filename],
+     *     // import.meta.filename means that changes to webpack.config.js should invalidate the cache
+     *     config: [import.meta.filename],
      * });
      *
      * // also configure other options the Webpack "cache" key
-     * Encore.enableBuildCache({ config: [__filename] }, (cache) => {
+     * Encore.enableBuildCache({ config: [import.meta.filename] }, (cache) => {
      *     cache.version: `${process.env.GIT_REV}`;
      *
      *     cache.name: `${env.target}`

lib/friendly-errors/formatters/missing-postcss-config.js

@@ -22,21 +22,27 @@ function formatErrors(errors) {
         pc.red('Module build failed: Error: No PostCSS Config found')
     );
     messages.push('');
-    messages.push(`${pc.bgGreen(pc.black('FIX'))} Create a ${pc.yellow('postcss.config.js')} file at the root of your project.`);
+    messages.push(`${pc.bgGreen(pc.black('FIX'))} Create a PostCSS config file at the root of your project.`);
     messages.push('');
-    messages.push('Here is an example to get you started!');
+    messages.push('Here are two examples to get you started:');
+    messages.push('');
+    messages.push(pc.bold('Option 1: ESM') + ` (${pc.yellow('postcss.config.js')})`);
+    messages.push(pc.yellow(`
+export default {
+  plugins: {
+    'autoprefixer': {},
+  }
+}
+    `));
+    messages.push(pc.bold('Option 2: CJS') + ` (${pc.yellow('postcss.config.cjs')})`);
     messages.push(pc.yellow(`
-// postcss.config.js
 module.exports = {
   plugins: {
     'autoprefixer': {},
   }
 }
     `));
 
-    messages.push('');
-    messages.push('');
-
     return messages;
 }