elm-css-modules-loader

CSS Modules for Elm

A Webpack loader that enables you to reference CSS modules in Elm source files.

Hat tip to NoRedInk and its elm-assets-loader, which formed the technical basis for this package.

Overview

Start with a CSS file that can be imported by Webpack using css-loader:

.something {
  ⋮
}

.anotherThing {
  ⋮
}

In any Elm module, reference this stylesheet and the classes you want to use in it:

module Styles exposing (..)

import CssModules exposing (CssModule(..))


classes =
    CssModule "./stylesheet.css" -- relative to main Elm source directory
        { something = "" -- strings will be populated by Webpack at build time!
        , anotherThing = ""
        }

Then use the included class function to use the class names in your view:

module Main exposing (..)

import CssModules exposing (class)
import Styles exposing (classes)


view : Html Msg
view =
    div
        [ class .something classes ]
        [ text "this is a div"]

Why does this exist?

We wanted to use the same style sheets for the standard components in our application (buttons, form fields, etc.) across two different implementations of these components (React and Elm). We love the namespacing and composition features of CSS Modules; this project seeks to make them usable within Elm views.

Note: elm-css is the de facto standard for writing styles for HTML interfaces written in Elm. If you are working on an all-Elm application, you should probably use that.

How to use

To get this working, you need to set up a combination of a Webpack loader and and Elm package.

Webpack Loader

Add the elm-css-modules-loader NPM package to your project, then configure Webpack to chain it with elm-webpack-loader:

module.exports = {
  ⋮
  module: {
    loaders: [
      {
        test: /\.elm$/,
        loaders: ['elm-css-modules-loader', 'elm-webpack'],
      },
      ⋮
    ],
  },
};

Elm Package

Install the cultureamp/elm-css-modules-loader package in your Elm project, then use the features provided: the CssModule constructor (for referencing CSS modules), and the class and classList HTML attribute functions.

Under the hood

Let’s walk through what happens when this Elm code is processed by Webpack:

classes =
    CssModule "./stylesheet.css"
        { something = ""
        , anotherThing = ""
        }

This will be compiled to JavaScript by elm-webpack-loader:

var _user$project$Styles$classes = A2(
  _user$project$CssModules$CssModule,
  './stylesheet.css',
  {something: '', anotherThing: ''});

elm-css-modules-loader turns this into:

var _user$project$Styles$classes = A2(
  _user$project$CssModules$CssModule,
  './stylesheet.css',
  require('./stylesheet.css'));

webpack parses this require call, determines it to be a css-loader module, resulting in:

var _user$project$Styles$classes = A2(
  _user$project$CssModules$CssModule,
  './stylesheet.css',
  __webpack_require__(42));

The module loaded by __webpack_require__(42) will look like:

42:
function(module, exports) {
  module.exports = {
    something: 'something-abc123',
    anotherThing: 'anotherThing-abc123' 
  };
}

Known Limitations

Currently this only works with Webpack 1.x. Webpack 2 support is at the top the our to-do list.

You cannot reference class names that are not valid Elm record keys.

Development Roadmap

1. Support Webpack 2.
2. Add robustness, tests.