@studyportals/webpack-helper 7.0.1-5 → 8.1.0

package/README.md

@@ -7,6 +7,10 @@ WebpackHelper is a utility that makes it easy to set up a webpack configuration
 - [Webpack version](#webpack-version)
   - [Notes on updating Webpack from v4 to v5](#notes-on-updating-webpack-from-v4-to-v5)
 - [Quick Start](#quick-start)
+- [SCSS Migration](#scss-migration-from-153x-to--1540)
+  - [Minimum compiler that shows each warning](#minimum-compiler-that-shows-each-warning)
+  - [Migration](#migration)
+    - [List of changes](#list-of-changes)
 - [Chunks Retry](#chunks-retry)
   - [Defaults](#defaults)
   - [Setup](#setup)
@@ -101,6 +105,75 @@ When your configuration is created you can get an instance of it for the correct
 module.exports = (env, details) => configuration.get(details.mode);
 ```
 
+## SCSS Migration from 1.53.x to >= 1.54.0
+
+This package is used by other services that build with `sass`. Each `sass` release is a JavaScript build of the same-numbered Dart Sass compiler, so bumping from 1.53.x to 1.54.0 silently enables a raft of breaking-change warnings. Eventually when Dart Sass 3 is released, these warnings become hard errors that will break downstream builds.
+
+| Dependency in *package.json* | Real compiler behind the scenes                                                                                    | Notes                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `"sass": "^1.89.2"`          | Dart Sass 1.89.2 (JS build)                                                                                        | Running `npx sass --version` shows the exact Dart Sass version. |
+| `"sass-loader": "^16"`       | Webpack loader that invokes **whatever Sass implementation you installed** (defaults to the `sass` package above). |                                                                 |
+
+### Minimum compiler that shows each warning
+
+| Change (see checklist below)                   | First **warns** in | Becomes an **error** |
+| ---------------------------------------------- | ------------------ | -------------------- |
+| Invalid combinators (`> >`, leading `+`, etc.) | 1.54.0             | already errors       |
+| Media-Query Level 4 logic                      | 1.54.0             | 1.56.0               |
+| Strict unary `+ -` spacing                     | 1.55.0             | already errors       |
+| Duplicate `!default`/`!global` flags           | 1.62.0             | already errors       |
+| Reserved `type()` function                     | 1.86.0             | next major           |
+| `/` division → `math.div()`                    | 1.33.0             | next major           |
+| `@import` → module system                      | 1.80.0             | Dart Sass 3          |
+
+### Migration
+
+To help us migrate, there is a package called `sass-migrator` that you can use to resolve the majority of the issues.
+
+```bash
+npm install --save-dev sass-migrator
+```
+
+Then run
+
+```bash
+# migrate @import → @use/@forward
+npx sass-migrator module --migrate-deps "src/**/*.scss"
+
+# replace “/” division with math.div()
+npx sass-migrator division --migrate-deps "src/**/*.scss"
+
+# add the required space for ambiguous + / - operators
+npx sass-migrator strict-unary --migrate-deps "src/**/*.scss"
+
+# swap legacy color helpers (lighten(), darken(), …) for sass:color APIs
+npx sass-migrator color --migrate-deps "src/**/*.scss"
+```
+
+#### List of changes
+
+| #  | Change you must make                            | **Before — old SCSS**                                                                                                      | **After — new SCSS**                                                                                                          | Why it matters                                                                          |
+| -- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| 1  | Replace **`@import` → `@use/@forward`**         | A) `@import "tools/colors";`<br>B) `@import "theme/light";`<br>    `@import "components/button";`                          | A) `@use "tools/colors" as colors;`<br>B) `@use "theme/light" as *;`<br>    `@use "components/button";`                       | `@import` builds a huge global namespace and re-parses files; removed in Dart Sass 3.0. |
+| 2  | Slash-division → **`math.div()`**               | A) `width: 100%/3;`<br>B) `$col: 940px/12;`                                                                                | `@use "sass:math";`<br>A) `width: math.div(100%, 3);`<br>B) `$col: math.div(940px, 12);`                                      | `/` is being re-defined as a list separator.                                            |
+| 3  | Make unary `+` / `-` unambiguous                | A) `gap: 10px -$space;`<br>B) `margin: +$n ($n*2);`                                                                        | A) `gap: 10px - $space;` or `gap: 10px (-$space);`<br>B) `margin: + $n (#{$n*2});`                                            | Compiler now errors on ambiguous signs.                                                 |
+| 4  | Rename a custom **`type()`** function           | A) `@function type($x) {…}`<br>B) `$v: type(42);`                                                                          | A) `@function kind($x) {…}`<br>B) `$v: kind(42);`                                                                             | CSS adds its own reserved `type()`.                                                     |
+| 5  | Swap legacy colour helpers for **`sass:color`** | A) `$hover: lighten($brand, 10%);`<br>B) `$new: adjust-hue($brand, 20deg);`                                                | `@use "sass:color";`<br>A) `$hover: color.adjust($brand, $lightness: 10%);`<br>B) `$new:  color.adjust($brand, $hue: 20deg);` | Old helpers assume sRGB only.                                                           |
+| 6  | Remove duplicate flags                          | A) `$pad: 1rem !default !default;`<br>B) `$debug: null !global !global;`                                                   | `$pad: 1rem !default;`<br>`$debug: null !global;`                                                                             | A second `!default`/`!global` is now an error.                                          |
+| 7  | Delete **`meta.feature-exists()`**              | A) `@use "sass:meta";`<br>  `@if meta.feature-exists("global-variable-shadowing") {…}`<br>B) `$has: feature-exists(calc);` | Usually just delete — all features it checks are always present.                                                              | Function is obsolete.                                                                   |
+| 8  | Fix stray / doubled combinators                 | A) `+ .alert {…}`<br>B) `nav > > li {…}`                                                                                   | A) `.alert {…}`<br>B) `nav > li {…}`                                                                                          | Invalid CSS selectors now error.                                                        |
+| 9  | Keep declarations **before** nested rules       | `.card {`<br>  `color:#333;`<br>  `&__header {…}`<br>  `font-weight:bold;`<br>`}`                                          | `.card {`<br>  `color:#333;`<br>  `&__header {…}`<br>  `& { font-weight:bold; }`<br>`}`                                       | Mirrors CSS Nesting source-order rules.                                                 |
+| 10 | Use CSS-4 logic in **`@media`**                 | A) `@media (not (prefers-reduced-motion)) {…}`<br>B) `@media ((hover) and (pointer:fine)) {…}`                             | `@media not (prefers-reduced-motion) {…}`<br>`@media (hover) and (pointer:fine) {…}`                                          | Old parenthesised syntax conflicts with MQ L4.                                          |
+| 11 | Always interpolate custom-prop values           | A) `--accent: $brand;`<br>B) `--size: $gap * 1.5;`                                                                         | `--accent: #{$brand};`<br>`--size: #{$gap * 1.5};`                                                                            | Stops Sass mistaking raw CSS tokens for vars.                                           |
+| 12 | Give colour funcs the right units               | A) `hsl(0.5turn,100%,50%);`<br>B) `$deg: 90grad; hue($c,$deg);`                                                            | A) `hsl(180deg,100%,50%);`<br>B) `$deg: 90deg; color.adjust($c,$hue:$deg);`                                                   | Functions now enforce CSS-spec units.                                                   |
+| 13 | Use **`math.abs()`** for percentages            | A) `$pos: abs(-10%);`<br>B) `padding: abs(5%);`                                                                            | `@use "sass:math";`<br>A) `$pos: math.abs(-10%);`<br>B) `padding: math.abs(5%);`                                              | Global `abs()` drops `%` support.                                                       |
+| 14 | Rename any name starting **`--`**               | A) `@mixin --theme($c){…}`<br>B) `@function --shadow(){…}`                                                                 | `@mixin _theme($c){…}`<br>`@function _shadow(){…}`                                                                            | `--` reserved for future native CSS mixins.                                             |
+| 15 | Remove special **`@-moz-document`** parser      | `@-moz-document url-prefix("https://") { … }`<br>`@-moz-document domain(mozilla.org) { … }`                                | *(Delete or treat as an unknown at-rule; only `@-moz-document url-prefix()` hack still compiles.)*                            | Feature gone from Firefox → dropped from Sass.                                          |
+| 16 | **Don’t `@extend` a compound selector**         | A) `.notice { @extend .msg.info; }`<br>B) `.alert { @extend .box.error; }`                                                 | `.notice { @extend .msg, .info; }`<br>`.alert  { @extend .box, .error; }`                                                     | Dart Sass forbids extending `.foo.bar`.                                                 |
+| 17 | **You can’t overwrite a mixin or function that came in via `@use`** | `@import "~@studyportals/styles-abstracts/abstracts.scss";`<br>`@include TextStyle($name);`<br>`font-weight: 700;`| `@use "~@studyportals/styles-abstracts/abstracts.scss" as *;`<br>`@include TextStyle($name);`| Error immediately since `@use` (1.23) — name collisions are blocked ([sass-lang.com][1]) |
+
+[1]: https://sass-lang.com/blog/the-module-system-is-launched/ "Sass: The Module System is Launched"
+
 ## Chunks Retry
 
 Webpack Helpers has a default configuration to retry chunks which cannot get loaded on the first try (for whatever reason, network or otherwise).

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@studyportals/webpack-helper",
-  "version": "7.0.1-5",
+  "version": "8.1.0",
   "description": "A collection of standard configurations and helpers for webpack.",
   "main": "src/main.js",
   "scripts": {
     "test": "vitest --watch=false --coverage",
     "build": "tsc",
     "prepublish": "npm run build",
-    "postinstall": "cp ./assets/.browserslistrc ../../../",
+    "postinstall": "test -d ../../../ && cp ./assets/.browserslistrc ../../../ || true",
     "deploy-beta": "npm version prerelease && npm run build && npm publish --tag beta --access=public  --auth-type=legacy &&  rm -rf node_modules"
   },
   "files": [
@@ -20,12 +20,10 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@babel/core": "^7.27.4",
     "@studyportals/bob-manifest-generator": "^5.0.1",
-    "@studyportals/browserslist-config": "^1.2.4",
+    "@studyportals/browserslist-config": "^2.0.0",
     "@studyportals/dll-availability-tracker": "^2.0.0",
     "@studyportals/vue-config": "^5.0.3",
-    "babel-loader": "^10.0.0",
     "css-loader": "^6.10.0",
     "css-minimizer-webpack-plugin": "^6.0.0",
     "esbuild-loader": "^4.0.3",
@@ -35,11 +33,9 @@
     "mini-css-extract-plugin": "^2.8.0",
     "path": "^0.12.7",
     "prettier": "^2.8.8",
-    "sass": "^1.71.1",
-    "sass-loader": "^14.1.1",
-    "swc-loader": "^0.2.6",
+    "sass": "^1.89.2",
+    "sass-loader": "^16.0.5",
     "terser-webpack-plugin": "^5.3.10",
-    "ts-loader": "^9.5.2",
     "typescript": "^5.3.3",
     "vue-loader": "^17.4.2",
     "webpack": "^5.90.3",

package/src/enums/preset.js

@@ -4,7 +4,6 @@ exports.Preset = void 0;
 var Preset;
 (function (Preset) {
     Preset["VUE_TYPESCRIPT"] = "vue-typescript";
-    Preset["VUE_TYPESCRIPT_SWC"] = "vue-typescript-swc";
     Preset["TYPESCRIPT"] = "typescript";
     Preset["JAVASCRIPT"] = "javascript";
 })(Preset || (exports.Preset = Preset = {}));

package/src/model/configuration.js

@@ -16,7 +16,6 @@ const mode_1 = require("../enums/mode");
 const production_config_1 = require("../defaults/production.config");
 const development_config_1 = require("../defaults/development.config");
 const chunks_retry_plugin_factory_1 = __importDefault(require("../factories/chunks-retry-plugin-factory"));
-const vue_typescript_swc_preset_1 = require("../presets/vue-typescript-swc.preset");
 const ManifestGenerator = require("@studyportals/bob-manifest-generator").ManifestGenerator;
 const DllReferencePlugin = require("@studyportals/bob-manifest-generator").DllReferencePlugin;
 const { merge } = require('webpack-merge');
@@ -70,8 +69,6 @@ class Configuration {
             case preset_1.Preset.VUE_TYPESCRIPT:
                 this.injectPreset(new vue_typescript_preset_1.VueTypeScriptPreset(mode, this.chunksRetryConfig, this.customElementTags));
                 break;
-            case preset_1.Preset.VUE_TYPESCRIPT_SWC:
-                this.injectPreset(new vue_typescript_swc_preset_1.VueTypescriptSwcPreset(mode, this.chunksRetryConfig, this.customElementTags));
             case preset_1.Preset.TYPESCRIPT:
                 this.injectPreset(new typescript_preset_1.TypeScriptPreset(mode, this.chunksRetryConfig));
                 break;

package/src/presets/typescript-swc.preset.js

@@ -1,75 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeScriptPreset = void 0;
-const browser_list_to_esbuild_target_factory_1 = require("../factories/browser-list-to-esbuild-target-factory");
-const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-class TypeScriptPreset {
-    constructor(mode, retryChunksConfig) {
-        this.mode = mode;
-        this.retryChunksConfig = retryChunksConfig;
-    }
-    getPlugins(filename) {
-        return [
-            new MiniCssExtractPlugin({
-                filename
-            }),
-        ];
-    }
-    getModule() {
-        return {
-            rules: [
-                {
-                    test: /\.css$/,
-                    use: [
-                        MiniCssExtractPlugin.loader,
-                        'css-loader'
-                    ],
-                },
-                {
-                    test: /\.scss$/,
-                    use: [
-                        MiniCssExtractPlugin.loader,
-                        'css-loader',
-                        {
-                            loader: 'sass-loader',
-                            options: {
-                                api: 'modern-compiler'
-                            }
-                        }
-                    ],
-                },
-                {
-                    test: /\.[jt]sx?$/,
-                    loader: 'esbuild-loader',
-                    options: {
-                        target: new browser_list_to_esbuild_target_factory_1.BrowserListToEsbuildTargetFactory().createTarget(),
-                        supported: {
-                            'class-static-blocks': false,
-                            'optional-chain': false,
-                        }
-                    },
-                    resolve: {
-                        fullySpecified: false
-                    },
-                    exclude: /node_modules\/(?!@studyportals\/).*/,
-                },
-                {
-                    test: /\.(png|jpg|gif|svg)$/,
-                    loader: 'file-loader',
-                    options: {
-                        name: '[name].[ext]?[fullhash]'
-                    }
-                }
-            ]
-        };
-    }
-    getExtensions() {
-        return [
-            '*',
-            '.ts',
-            '.js',
-            '.json'
-        ];
-    }
-}
-exports.TypeScriptPreset = TypeScriptPreset;

package/src/presets/vue-typescript-swc.preset.js

@@ -1,106 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VueTypescriptSwcPreset = void 0;
-const mode_1 = require("../enums/mode");
-const webpack = require("webpack");
-const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-const VueLoaderPlugin = require('vue-loader').VueLoaderPlugin;
-const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
-class VueTypescriptSwcPreset {
-    constructor(mode, retryChunksConfig, customElementTags) {
-        this.mode = mode;
-        this.retryChunksConfig = retryChunksConfig;
-        this.customElementTags = customElementTags;
-        console.log(`[VueTypescriptSwcPreset] Constructor called for mode: ${mode}`);
-    }
-    getPlugins(filename) {
-        return [
-            new ForkTsCheckerWebpackPlugin(),
-            new webpack.DllReferencePlugin({
-                manifest: require(`@studyportals/vue-config/dist/vue3_library_v5${this.mode === mode_1.Mode.PRODUCTION ? '.min' : ''}.json`)
-            }),
-            new MiniCssExtractPlugin({
-                filename,
-                ignoreOrder: true
-            }),
-            new VueLoaderPlugin()
-        ];
-    }
-    getModule() {
-        return {
-            rules: [
-                {
-                    test: /\.css$/,
-                    use: [
-                        MiniCssExtractPlugin.loader,
-                        'css-loader'
-                    ],
-                },
-                {
-                    test: /\.scss$/,
-                    use: [
-                        MiniCssExtractPlugin.loader,
-                        'css-loader',
-                        'sass-loader'
-                    ],
-                },
-                {
-                    test: /\.vue$/,
-                    loader: 'vue-loader',
-                    options: {
-                        loaders: {
-                            'scss': [
-                                'vue-style-loader',
-                                'css-loader',
-                                'sass-loader'
-                            ]
-                        },
-                        hotReload: false,
-                    }
-                },
-                {
-                    test: /\.(ts|js)x?$/,
-                    exclude: /node_modules/,
-                    use: {
-                        loader: 'swc-loader',
-                        options: {
-                            jsc: {
-                                keepClassNames: true,
-                                parser: {
-                                    syntax: 'typescript',
-                                    tsx: true,
-                                    decorators: true,
-                                },
-                                transform: {
-                                    legacyDecorator: true,
-                                    decoratorMetadata: true
-                                },
-                                target: 'es6'
-                            },
-                            module: {
-                                type: 'es6'
-                            }
-                        }
-                    }
-                },
-                {
-                    test: /\.(png|jpg|gif|svg)$/,
-                    loader: 'file-loader',
-                    options: {
-                        name: '[name].[ext]?[fullhash]'
-                    }
-                },
-            ]
-        };
-    }
-    getExtensions() {
-        return [
-            '*',
-            '.ts',
-            '.js',
-            '.vue',
-            '.json'
-        ];
-    }
-}
-exports.VueTypescriptSwcPreset = VueTypescriptSwcPreset;