@emulsify/core 3.0.4 → 3.1.1

package/.github/workflows/addtoprojects.yml

@@ -17,5 +17,5 @@ jobs:
         with:
           # You can target a repository in a different organization
           # to the issue
-          project-url: https://github.com/orgs/emulsify-ds/projects/6
+          project-url: https://github.com/emulsify-ds/emulsify-core
           github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

package/.github/workflows/lint.yml

@@ -9,13 +9,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Install Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: "24"
       - name: Install
         run: npm install
       - name: Lint

package/config/webpack/loaders.js

@@ -1,42 +1,65 @@
 /**
- * @fileoverview Configures Webpack loaders.
+ * @fileoverview Webpack loader configurations for Emulsify Core and per-project overrides.
+ *
+ * This module exports a single default object containing loader definitions for:
+ *   - JavaScript (with Babel)
+ *   - Sass/CSS (with PostCSS + Autoprefixer or project overrides)
+ *   - Images
+ *   - SVG sprites
+ *   - Twig templates
+ *
+ * It will look for these override files in your project:
+ *   - ./config/emulsify-core/webpack/babel.config.cjs
+ *   - ./config/emulsify-core/webpack/postcss.config.cjs
+ *
+ * If not found, it falls back to the package defaults.
  */
 
+import { createRequire } from 'module';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import globImporter from 'node-sass-glob-importer';
 import fs from 'fs-extra';
+import path from 'path';
 
-let babelConfig;
-let postcssConfig;
+const require = createRequire(import.meta.url);
 
-// Check if custom babel config is available.
-if (fs.existsSync('./config/emulsify-core/webpack/babel.config.cjs')) {
-  babelConfig = './config/emulsify-core/webpack/babel.config.cjs';
-} else {
-  babelConfig = './node_modules/@emulsify/core/config/babel.config.js';
-}
+/** @type {string} Path to the active Babel config file. */
+const babelConfig = fs.existsSync(
+  './config/emulsify-core/webpack/babel.config.cjs',
+)
+  ? './config/emulsify-core/webpack/babel.config.cjs'
+  : require.resolve('@emulsify/core/config/babel.config.js');
 
-// Check if custom postcss config is available.
-if (fs.existsSync('./config/emulsify-core/webpack/postcss.config.cjs')) {
-  postcssConfig = './config/emulsify-core/webpack/postcss.config.cjs';
-} else {
-  postcssConfig = './node_modules/@emulsify/core/config/postcss.config.js';
-}
+/** @type {string} Path to the active PostCSS config file. */
+const postcssConfigPath = fs.existsSync(
+  './config/emulsify-core/webpack/postcss.config.cjs',
+)
+  ? path.resolve('config/emulsify-core/webpack/postcss.config.cjs')
+  : require.resolve('@emulsify/core/config/postcss.config.js');
 
+/**
+ * @type {import('webpack').RuleSetRule}
+ * JavaScript loader: transpile with Babel.
+ */
 const JSLoader = {
   test: /^(?!.*\.(stories|component)\.js$).*\.js$/,
   exclude: /node_modules/,
-  loader: 'babel-loader',
-  options: {
-    configFile: babelConfig,
+  use: {
+    loader: 'babel-loader',
+    options: {
+      configFile: babelConfig,
+    },
   },
 };
 
-const ImageLoader = {
-  test: /\.(png|jpe?g|gif)$/i,
-  type: 'asset',
-};
-
+/**
+ * @type {import('webpack').RuleSetRule}
+ * CSS/Sass loader chain:
+ *   - extract to file
+ *   - css-loader (no URL rewriting)
+ *   - postcss-loader (project or default)
+ *   - sass-loader (with glob importer + compressed output)
+ */
 const CSSLoader = {
   test: /\.s[ac]ss$/i,
   exclude: /node_modules/,
@@ -54,8 +77,7 @@ const CSSLoader = {
       options: {
         sourceMap: true,
         postcssOptions: {
-          config: postcssConfig,
-          plugins: [['autoprefixer']],
+          config: postcssConfigPath,
         },
       },
     },
@@ -64,16 +86,33 @@ const CSSLoader = {
       options: {
         api: 'legacy',
         sourceMap: true,
+        implementation: require('sass'),
+        webpackImporter: true,
         sassOptions: {
           importer: globImporter(),
+          legacyImporter: true,
           outputStyle: 'compressed',
           silenceDeprecations: ['legacy-js-api'],
+          quietDeps: true,
         },
       },
     },
   ],
 };
 
+/**
+ * @type {import('webpack').RuleSetRule}
+ * Image loader: inlines small assets, emits larger ones.
+ */
+const ImageLoader = {
+  test: /\.(png|jpe?g|gif)$/i,
+  type: 'asset',
+};
+
+/**
+ * @type {import('webpack').RuleSetRule}
+ * SVG sprite loader: collects all /icons/*.svg into one sprite.
+ */
 const SVGSpriteLoader = {
   test: /icons\/.*\.svg$/,
   use: [
@@ -90,6 +129,10 @@ const SVGSpriteLoader = {
   ],
 };
 
+/**
+ * @type {import('webpack').RuleSetRule}
+ * Twig.js loader for .twig templates.
+ */
 const TwigLoader = {
   test: /\.twig$/,
   use: {
@@ -97,10 +140,14 @@ const TwigLoader = {
   },
 };
 
+/**
+ * Default export of all loader configurations.
+ * @type {{ JSLoader: import('webpack').RuleSetRule, CSSLoader: import('webpack').RuleSetRule, ImageLoader: import('webpack').RuleSetRule, SVGSpriteLoader: import('webpack').RuleSetRule, TwigLoader: import('webpack').RuleSetRule }}
+ */
 export default {
   JSLoader,
   CSSLoader,
-  SVGSpriteLoader,
   ImageLoader,
+  SVGSpriteLoader,
   TwigLoader,
 };

package/config/webpack/plugins.js

@@ -1,95 +1,136 @@
-/**
- * @fileoverview Configures Webpack plugins.
- */
-
 import { resolve, dirname } from 'path';
 import webpack from 'webpack';
 import { CleanWebpackPlugin } from 'clean-webpack-plugin';
-import _MiniCssExtractPlugin from 'mini-css-extract-plugin';
-import _SpriteLoaderPlugin from 'svg-sprite-loader/plugin.js';
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import SpriteLoaderPlugin from 'svg-sprite-loader/plugin.js';
 import CopyPlugin from 'copy-webpack-plugin';
 import { sync as globSync } from 'glob';
 import fs from 'fs-extra';
 import emulsifyConfig from '../../../../../project.emulsify.json' with { type: 'json' };
 
-// Create __filename from import.meta.url without fileURLToPath
-let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
-
-// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
-if (process.platform === 'win32' && _filename.startsWith('/')) {
-  _filename = _filename.slice(1);
+/**
+ * Resolve the directory of this file (without fileURLToPath).
+ * @type {string}
+ */
+let __filename = decodeURIComponent(new URL(import.meta.url).pathname);
+if (process.platform === 'win32' && __filename.startsWith('/')) {
+  __filename = __filename.slice(1);
 }
+const __dirname = dirname(__filename);
 
-const _dirname = dirname(_filename);
-
-const projectDir = resolve(_dirname, '../../../../..');
-const srcDir = resolve(projectDir, 'src');
-
-const MiniCssExtractPlugin = new _MiniCssExtractPlugin({
-  filename: '[name].css',
-  chunkFilename: '[id].css',
-});
+/**
+ * Root of the project (three levels up from this file).
+ * @type {string}
+ */
+const projectDir = resolve(__dirname, '../../../../..');
 
-const SpriteLoaderPlugin = new _SpriteLoaderPlugin({
-  plainSprite: true,
-});
+/**
+ * Where your source files live (if you have a `/src` folder).
+ * Falls back to `components/` if `src/` does not exist.
+ * @type {string}
+ */
+const srcPath = resolve(projectDir, 'src');
+const isSrcExists = fs.pathExistsSync(srcPath);
+const srcDir = isSrcExists ? srcPath : resolve(projectDir, 'components');
 
-const ProgressPlugin = new webpack.ProgressPlugin();
+/**
+ * Where your built assets should live.
+ * Mirrors the `srcDir` logic: prefer `dist/` if you have `src/`, else `components/`.
+ * @type {string}
+ */
+const distPath = isSrcExists
+  ? resolve(projectDir, 'dist')
+  : resolve(projectDir, 'components');
 
+/**
+ * Glob pattern for all Twig & component files in your source.
+ * We copy these through CopyPlugin so your PHP/Drupal theme sees them.
+ * @type {string}
+ */
 const componentFilesPattern = resolve(
   srcDir,
   '**/*.{twig,component.yml,component.json}',
 );
 
 /**
- * Prepare a list of patterns for copying Twig and component files.
+ * Turn a globbed source list into copy patterns.
  *
- * @param {string} filesMatcher - Glob pattern for matching files.
- * @returns {Array<Object>} Array of objects with `from` and `to` properties.
+ * @param {string} filesMatcher Glob pattern.
+ * @returns {Array<{from:string,to:string}>}
  */
 function getPatterns(filesMatcher) {
-  const patterns = [];
-  globSync(filesMatcher).forEach((file) => {
+  return globSync(filesMatcher).map((file) => {
     const projectPath = file.split('/src/')[0];
     const srcStructure = file.split(`${srcDir}/`)[1];
     const parentDir = srcStructure.split('/')[0];
-    const filePath = file.split(/(foundation\/|components\/|layout\/)/)[2];
+    // Consolidate foundation/layout under components for Drupal.
     const consolidateDirs =
       parentDir === 'layout' || parentDir === 'foundation'
         ? '/components/'
         : '/';
-    const newfilePath =
+    const filePath = file.split(/(foundation\/|components\/|layout\/)/)[2];
+    const destDir =
       emulsifyConfig.project.platform === 'drupal'
         ? `${projectPath}${consolidateDirs}${parentDir}/${filePath}`
         : `${projectPath}/dist/${parentDir}/${filePath}`;
-    patterns.push({
-      from: file,
-      to: newfilePath,
-    });
+    return { from: file, to: destDir };
   });
-  return patterns;
 }
 
-const CopyTwigPlugin = fs.pathExistsSync(resolve(projectDir, 'src'))
+/**
+ * Only include CopyPlugin if we actually have a `src/` folder.
+ * @type {CopyPlugin|false}
+ */
+const CopyTwigPlugin = isSrcExists
   ? new CopyPlugin({ patterns: getPatterns(componentFilesPattern) })
-  : '';
+  : false;
+
+/**
+ * CleanWebpackPlugin configuration.
+ * Wipes out everything in `distPath` before a build,
+ * except image files (we whitelist common image extensions).
+ */
+const CleanPlugin = new CleanWebpackPlugin({
+  protectWebpackAssets: false,
+  cleanOnceBeforeBuildPatterns: [
+    // wipe all compiled assets
+    `${distPath}/**/*.css`,
+    `${distPath}/**/*.js`,
+    // but keep any images
+    `!${distPath}/**/*.png`,
+    `!${distPath}/**/*.jpg`,
+    `!${distPath}/**/*.gif`,
+    `!${distPath}/**/*.svg`,
+  ],
+});
+
+/**
+ * MiniCssExtractPlugin instance: writes `[name].css` into your dist.
+ */
+const CssExtractPlugin = new MiniCssExtractPlugin({
+  filename: '[name].css',
+  chunkFilename: '[id].css',
+});
 
-const pluginConfig = {
+/**
+ * svg-sprite-loader plugin: bundles all /icons/*.svg.
+ */
+const SpritePlugin = new SpriteLoaderPlugin({
+  plainSprite: true,
+});
+
+/**
+ * webpack.ProgressPlugin for nice build progress output.
+ */
+const ProgressPlugin = new webpack.ProgressPlugin();
+
+/**
+ * Export all plugins keyed for easy inclusion in your final Webpack config.
+ */
+export default {
   ProgressPlugin,
-  MiniCssExtractPlugin,
-  SpriteLoaderPlugin,
+  CleanWebpackPlugin: CleanPlugin,
+  MiniCssExtractPlugin: CssExtractPlugin,
+  SpriteLoaderPlugin: SpritePlugin,
   CopyTwigPlugin,
-  CleanWebpackPlugin: new CleanWebpackPlugin({
-    protectWebpackAssets: false,
-    cleanOnceBeforeBuildPatterns: ['!*.{png,jpg,gif,svg}'],
-    cleanAfterEveryBuildPatterns: [
-      'remove/**',
-      '!js',
-      'css/**/*.js',
-      'css/**/*.js.map',
-      '!*.{png,jpg,gif,svg}',
-    ],
-  }),
 };
-
-export default pluginConfig;

package/config/webpack/resolves.js

@@ -23,6 +23,10 @@ const srcDir = fs.pathExistsSync(resolve(projectDir, 'src'))
   ? resolve(projectDir, 'src')
   : resolve(projectDir, 'components');
 
+if (!fs.pathExistsSync(resolve(srcDir))) {
+  fs.mkdirSync(srcDir, { recursive: true });
+}
+
 const aliasPattern = resolve(srcDir, '**/!(_*).twig');
 
 /**

package/config/webpack/webpack.common.js

@@ -217,4 +217,9 @@ export default {
   },
   resolve: resolves.TwigResolve,
   optimization: optimizers,
+  ignoreWarnings: [
+    (warning) =>
+      warning.message &&
+      /Sass @import rules are deprecated/.test(warning.message),
+  ],
 };

package/config/webpack/webpack.dev.js

@@ -1,4 +1,4 @@
-import fs from 'fs';
+import fs from 'fs-extra';
 import { resolve, dirname } from 'path';
 import { merge } from 'webpack-merge';
 import common from './webpack.common.js';
@@ -16,16 +16,18 @@ if (process.platform === 'win32' && _filename.startsWith('/')) {
 
 const _dirname = dirname(_filename);
 
-const isDrupal = emulsifyConfig.project.platform === 'drupal';
+// Get directories for file contexts.
+const projectDir = resolve(_dirname, '../../../../..');
 
-// Resolve the src directory alongside how you’re already locating project.emulsify.json
-const srcDir = resolve(_dirname, '../../../../../src');
+const srcPath = resolve(projectDir, 'src');
+const srcExists = fs.pathExistsSync(srcPath);
+const isDrupal = emulsifyConfig.project.platform === 'drupal';
 
 // Always ignore dist
 const ignored = ['**/dist/**'];
 
 // If it’s Drupal and there is no src/, also ignore components
-if (isDrupal && !fs.existsSync(srcDir)) {
+if (isDrupal && srcExists) {
   ignored.push('**/components/**');
 }
 
@@ -33,7 +35,6 @@ export default merge(common, {
   mode: 'development',
   devtool: 'source-map',
   watchOptions: {
-    // You can supply a RegExp, glob strings, or an array thereof
     ignored,
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "3.0.4",
+  "version": "3.1.1",
   "description": "Bundled tooling for Storybook development + Webpack Build",
   "keywords": [
     "component library",
@@ -50,11 +50,11 @@
     "twatch": "jest --no-coverage --watch --verbose"
   },
   "dependencies": {
-    "@babel/core": "^7.27.4",
+    "@babel/core": "^7.27.7",
     "@babel/eslint-parser": "^7.27.5",
     "@babel/preset-env": "^7.27.2",
     "@emulsify/cli": "^1.11.4",
-    "@eslint/js": "^9.28.0",
+    "@eslint/js": "^9.30.0",
     "@storybook/addon-a11y": "^8.6.14",
     "@storybook/addon-actions": "^8.6.14",
     "@storybook/addon-essentials": "^8.6.14",
@@ -74,14 +74,14 @@
     "breakpoint-sass": "^3.0.0",
     "chalk": "^5.4.1",
     "clean-webpack-plugin": "^4.0.0",
-    "concurrently": "^9.1.2",
+    "concurrently": "^9.2.0",
     "copy-webpack-plugin": "^13.0.0",
     "css-loader": "^7.1.1",
-    "eslint": "^9.28.0",
+    "eslint": "^9.30.0",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jest": "^28.13.5",
-    "eslint-plugin-prettier": "^5.4.1",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jest": "^29.0.1",
+    "eslint-plugin-prettier": "^5.5.1",
     "eslint-plugin-security": "^3.0.1",
     "eslint-plugin-storybook": "^0.12.0",
     "eslint-webpack-plugin": "^5.0.2",
@@ -95,8 +95,8 @@
     "imagemin-gifsicle": "^7.0.0",
     "imagemin-jpegtran": "^8.0.0",
     "imagemin-optipng": "^8.0.0",
-    "jest": "^30.0.0",
-    "jest-environment-jsdom": "^30.0.0",
+    "jest": "^30.0.3",
+    "jest-environment-jsdom": "^30.0.2",
     "js-yaml": "^4.1.0",
     "js-yaml-loader": "^1.2.2",
     "mini-css-extract-plugin": "^2.9.2",
@@ -104,16 +104,16 @@
     "normalize.css": "^8.0.1",
     "open-cli": "^8.0.0",
     "pa11y": "^9.0.0",
-    "postcss": "^8.5.5",
+    "postcss": "^8.5.6",
     "postcss-loader": "^8.1.1",
     "postcss-scss": "^4.0.9",
-    "ramda": "^0.30.1",
+    "ramda": "^0.31.3",
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.89.2",
     "sass-loader": "^16.0.5",
     "storybook": "^8.6.14",
     "style-dictionary": "^4.4.0",
-    "stylelint": "^16.20.0",
+    "stylelint": "^16.21.0",
     "stylelint-config-standard-scss": "^15.0.1",
     "stylelint-prettier": "^5.0.3",
     "stylelint-selector-bem-pattern": "^4.0.1",
@@ -138,7 +138,7 @@
     "@semantic-release/release-notes-generator": "^14.0.3",
     "all-contributors-cli": "^6.26.1",
     "husky": "^9.1.7",
-    "lint-staged": "^16.1.0",
+    "lint-staged": "^16.1.2",
     "semantic-release": "^24.2.5"
   },
   "overrides": {