feat: add compat modes

Author: jquense

README.md

@@ -0,0 +1,199 @@
+# `css-module-loader`
+
+An implementation of webpack CSS module support independent of `css-loader`.
+
+## Usage
+
+```sh
+yarn add css-module-loader -D
+```
+
+To configure, add `css-module-loader` _immediately_ after `css-loader`, disable
+any existing module options on `css-loader`.
+
+**webpack.config.js**
+
+```diff
+{
+  ...
+  module: {
+    rules: [
+      {
+        test: /\.module\.css$/
+        use: [
+          'style-loader',
+          {
+            loader: 'css-loader',
+            options: {
+-             modules: true
++             importLoaders: 1,
+            }
+          },
++         'css-module-loader'
+        ]
+      }
+    ]
+  }
+}
+```
+
+If you are using css modules with a preprocessor, make sure that `css-module-loader` comes before them. It should only receive CSS (plus CSS module syntax)
+
+```diff
+  test: /\.module\.css$/,
+  use: [
+    'style-loader',
+    {
+      loader: 'css-loader',
+      options: {
+-       importLoaders: 1
++       importLoaders: 2
+      }
+    },
++   'css-module-loader',
+    'sass-loader'
+  ]
+```
+
+## Differences Between `css-loader`
+
+There are two big differences between the existing support in
+`css-loader`.
+
+The first is that it's not coupled to css-loader. By not being embedded in `css-loader`, users have more flexibility around upgrades, extensions and modifications. We can also update `css-module-loader` independently!
+
+The second difference is that `css-module-loader` does not use the original
+css-modules implementation. Instead, it is built on top of [modular-css](https://m-css.com/). `modular-css` is an actively developed off shoot of the original css-modules. It has more features, less footguns, and better and broader tooling support.
+
+### Why not use the "official" css-modules?
+
+The original css module tooling is mostly abandoned at this point. The original
+authors have moved on to new things and much of the tooling is stuck in a "bug fix" only limbo. This hasn't been a severe problem because css-modules is very
+stable, and fairly simple, but there are a lot of sharp edges in the implementation, that prevents certain DX improvements, like more helpful errors.
+
+On the other hand `modular-css` is actively maintained, as well as very stable. It addresses a bunch of the css-modules sharp edges (like ambigious scoping rules) and adds in a few quality of life features, like `:external` and module level `composes`. `modular-css` is also much easier to extend and hack on!
+
+### Migrating from css-loader
+
+In many cases the switch to `modular-css` should be transparent, many of the "breaking" differences are around less common usage patterns. Even still, `css-module-loader` includes a "compat" mode that should help ease the transition
+
+Enable compat mode via a loader option:
+
+```js
+  {
+    loader: 'css-module-loader',
+    options: {
+      compat: true
+    }
+  }
+```
+
+Different compatibilty plugins can also be more finely enabled/disabled
+
+```js
+  {
+    loader: 'css-module-loader',
+    options: {
+      compat: {
+        scoping: false,
+        valueAliasing: false,
+        icssImports: true,
+        icssExports: true,
+      }
+    }
+  }
+```
+
+The compatiblity plugins are outlined below:
+
+#### `scoping`
+
+ref: https://m-css.com/guide/#global
+
+`css-modules` allows `:global` and `:local` scoping to nest, wheras `modular-css` only allows the `:global(.foo)` pseudo for marking a selector
+as global.
+
+**When to enable:** If your code contains none-parameterized `:global` or `:local` pseudos like
+
+```css
+.my-class :global .token {
+}
+```
+
+**How to migrate:** Change to the parameterized form `:global(.token) {}`
+
+#### `valueAliasing`
+
+`css-modules` version of `@value`s allows for individually aliasing imported names:
+
+```css
+@value primary as utilsPrimary from './utils.css';
+
+.foo {
+  color: utilsPrimary;
+}
+```
+
+`modular-css` only (currently) allows importing by the exact name OR namespacing the entire import
+like: `@value * as utils from './utils.css';`
+
+> Note: enabling this will also enable `icssImports` which is used to implement it.
+
+**When to enable:** If you `@value` aliases, e.g.
+
+```css
+@value primary as utilsPrimary from './utils.css';
+```
+
+**How to migrate:** Switch to using `@value * as ns` to handle conflicts (see: https://m-css.com/guide/#namespaces)
+
+```css
+@value * as utils from './utils.css';
+
+.foo {
+  color: utils.primary;
+}
+```
+
+#### `icssExports`
+
+A very niche feature of css-modules that you may not even know is possible.
+css-modules, contains a little IL (intermediary language) for defining imports and exports manually. Generally this is only used by tooling, as part of a compile step, but it is possible to write manually as well.
+
+**When to enable:** If your code contains explicit `:export {}` rules
+
+```css
+:export {
+  myColor: red;
+  navbarHeight: 4rem;
+}
+```
+
+**How to migrate:** Switch to using `@value` (see: https://m-css.com/guide/#values)
+
+#### `icssImports`
+
+The pair to `icssExports`, allows importing and replacing local values via the ICSS
+import syntax
+
+**When to enable:** If your code contains explicit `:import("./file.css") {}` rules
+
+```css
+:import('./utils.css') {
+  utilsPrimary: primary;
+}
+
+.foo {
+  color: utilsPrimary;
+}
+```
+
+**How to migrate:** Switch to using `@value` and `@value * as ns` (see: https://m-css.com/guide/#values)
+
+### Other notable (small) differences
+
+These are things that aren't easy to write a compat plugin for and so may need
+direct migration.
+
+- importing `@value` from other files can only import actual `@value`s not classes
+- `@value`s are not replaced in selectors. use `:external` to reference identifiers from other files

example/.eslintrc

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "browser": true
+  }
+}

example/index.js

@@ -0,0 +1,7 @@
+const styles = require('./styles/button.module.css');
+
+document.body.innerHTML = `
+  <div>
+    <button class="${styles.foo}">button</p>
+  </div>
+`;

example/styles/button.module.css

@@ -0,0 +1,6 @@
+@value * as utils from './utils.module.css';
+
+.foo {
+  color: blue;
+  background-color: utils.bgColor;
+}

example/styles/utils.module.css

@@ -0,0 +1 @@
+@value bgColor: palevioletred;

example/webpack.config.js

@@ -0,0 +1,31 @@
+const ExtractCSS = require('mini-css-extract-plugin');
+const { plugins } = require('webpack-atoms');
+
+module.exports = {
+  entry: './index.js',
+  context: __dirname,
+  output: {
+    publicPath: '/',
+    filename: 'main.js',
+    path: `${__dirname}/build`,
+  },
+  devServer: {
+    contentBase: './build',
+    disableHostCheck: true,
+    historyApiFallback: true,
+    stats: 'minimal',
+  },
+  module: {
+    rules: [
+      {
+        test: /\.module\.css/,
+        use: [
+          ExtractCSS.loader,
+          { loader: 'css-loader', options: { importLoaders: 1 } },
+          { loader: require.resolve('../lib/loader.js'), options: {} },
+        ],
+      },
+    ],
+  },
+  plugins: [plugins.html(), new ExtractCSS()],
+};

lib/Utils.js

@@ -0,0 +1,19 @@
+const mapValues = require('lodash/mapValues');
+const findLast = require('lodash/findLast');
+
+function getExports(file, messages, opts = {}) {
+  const lastClsMsg = findLast(messages, 'classes');
+
+  return Object.assign(
+    {},
+    opts.exportValues ? mapValues(file.values, ({ value }) => value) : null,
+    lastClsMsg.classes,
+    ...messages
+      .filter(m => m.plugin && m.plugin.startsWith('modular-css-export'))
+      .map(m => m.exports),
+  );
+}
+
+module.exports = {
+  getExports,
+};

lib/loader.js

@@ -1,3 +1,5 @@
+const path = require('path');
+
 const Processor = require('@modular-css/processor');
 const { promisify } = require('util');
 const { getOptions } = require('loader-utils');
@@ -6,6 +8,13 @@ const getLocalName = require('./getLocalName');
 const PROCESSOR = Symbol('@modular-css processor');
 const CACHE = Symbol('loadModule cache module');
 
+const compatPlugins = {
+  scoping: require('./plugins/compat-scope-pseudos'),
+  valueAliasing: require('./plugins/compat-value-aliasing'),
+  icssImport: require('./plugins/compat-icss-import'),
+  icssExport: require('./plugins/compat-icss-export'),
+};
+
 function getLoadFilePrefix(loaderContext) {
   // loads a file with all loaders configured after this one
   const loadersRequest = loaderContext.loaders
@@ -19,21 +28,41 @@ function getLoadFilePrefix(loaderContext) {
 function loader(src) {
   const { resourcePath, _compilation: compilation } = this;
   const cb = this.async();
+  const fs = this._compilation.inputFileSystem;
 
   const options = getOptions(this) || {};
 
   const prefix = getLoadFilePrefix(this);
 
+  const resolver = (from, file) => {
+    let resolved = file.replace(/^~/, '');
+    if (!path.isAbsolute(resolved)) {
+      resolved = path.resolve(path.dirname(from), file);
+    }
+
+    try {
+      fs.statSync(resolved);
+      return resolved;
+    } catch (err) {
+      console.log(err);
+      return false;
+    }
+  };
+
   const loadFile = promisify((file, done) => {
+    // console.log('LOAD FILE');
     if (compilation[CACHE].has(file)) {
       done(null, compilation[CACHE].get(file));
       return;
     }
 
     this.loadModule(`${prefix}${file}`, (err, moduleSource) => {
-      const content = JSON.parse(moduleSource.toString());
-      // console.log('CACHE', file)
-      compilation[CACHE].set(file, content);
+      let content = '';
+      if (moduleSource) {
+        content = JSON.parse(moduleSource.toString());
+        compilation[CACHE].set(file, content);
+      }
+
       done(err, content);
     });
   });
@@ -43,18 +72,41 @@ function loader(src) {
   }
 
   if (!compilation[PROCESSOR]) {
-    compilation[PROCESSOR] = new Processor({
+    let compat = !options.compat ? [] : Object.entries(compatPlugins);
+
+    if (typeof options.compat === 'object') {
+      const names = new Set(
+        Object.entries(options.compat)
+          .filter(e => e[1])
+          .map(e => e[0]),
+      );
+
+      compat = compat.filter(e => names.has(e[0]));
+    }
+
+    compat = compat.map(([, plugin]) => plugin);
+
+    const mCssOptions = {
+      exportGlobals: false,
       ...options,
       loadFile,
       // this isn't run, b/c we don't combine css, but it'd be wrong
       // to do anyway since webpack handles it.
       rewrite: false,
+      resolvers: [resolver, ...(options.resolvers || [])],
       namer: (filename, localName) =>
         getLocalName(filename, localName, this, options),
-      processing: [require('./plugins/icss-import-export')]
-        .concat(options.processing)
+      before: compat
+        .filter(p => p.phase === 'before')
+        .concat(options.before)
         .filter(Boolean),
-    });
+      processing: []
+        .concat(compat.filter(p => p.phase === 'processing'))
+        .concat(require('./plugins/icss-import-export'), options.processing)
+        .filter(Boolean),
+    };
+
+    compilation[PROCESSOR] = new Processor(mCssOptions);
   }
 
   const processor = compilation[PROCESSOR];