@greenwood/plugin-css-modules

Overview

A Greenwood plugin for authoring CSS Modules ™️. It is a modest implementation of the specification. 🙂

This is NOT to be confused with CSS Module Scripts, which Greenwood already supports. For more information and complete docs on Greenwood, please visit our website.

This package assumes you already have @greenwood/cli installed.

Installation

You can use your favorite JavaScript package manager to install this package.

# npm
$ npm i -D @greenwood/plugin-css-modules

# yarn
$ yarn add @greenwood/plugin-css-modules --dev

# pnpm
$ pnpm add -D @greenwood/plugin-css-modules

Usage

Add this plugin to your greenwood.config.js:

import { greenwoodPluginCssModules } from '@greenwood/plugin-css-modules';

export default {
  // ...

  plugins: [
    greenwoodPluginCssModules()
  ]
}

Now you can create a CSS file that ends in .module.css:

/* header.module.css */
.container {
  display: flex;
  justify-content: space-between;
}

.navBarMenu {
  border: 1px solid #020202;
}

.navBarMenuItem {
  & a {
    text-decoration: none;
    color: #020202;
  }
}

@media screen and (min-width: 768px) {
  .container {
    padding: 10px 20px;
  }
}

And reference that in your (Light DOM) HTML based Web Component:

// header.js
import styles from './header.module.css';

export default class Header extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <header class="${styles.container}">
        <ul class="${styles.navBarMenu}">
          <li class="${styles.navBarMenuItem}">
            <a href="/about/" title="Documentation">About</a>
          </li>
          <li class="${styles.navBarMenuItem}">
            <a href="/contact/" title="Guides">Contact</a>
          </li>
        </ul>
      </header>
    `;
  }
}

customElements.define('app-header', Header);

From there, Greenwood will scope your CSS by prefixing with the filename and a hash, and inline that into a <style> tag in the HTML and strip the reference to the module.css file from your JavaScript file.

Caveats

This plugin aims to cover a representative majority of the specification, though if you find missing capabilities please consider submitting an issue and / or PR!

There are some caveats to consider when using this plugin:

1. This plugin only supports usage of CSS Modules within vanilla JavaScript, or TypeScript (.ts) and JSX (.jsx) when combined with our plugins
2. This plugin only checks for lower camelCase based class names

   /* works ✅ */
   .navBar { }
   
   /* does not work 🚫 */
   .nav-bar { }

3. Destructuring is not supported, so this will not work

   import styles from './header.module.css';
   
   export default class Header extends HTMLElement {
     connectedCallback() {
       const { container, navBar, ... } = styles;
   
       // ...
     }
   }
   
   customElements.define('app-header', Header);

4. From the spec, exporting @value variables is not supported