elm-css-modules-helper

Provide helper functions to handle CSS modules in Elm without hacks.

What is this?

This is an Elm library making it easy to use CSS modules in Elm.

There are cultureamp/elm-css-modules-loader for the same purpose, but this library does not do any hacks such as editing generated JS codes. Instead of using hacks, the only thing this library do is providing helper functions to handle JSON object provided via flags.

Steps to use CSS modules by elm-css-modules-helper

1. Generate JSON object that tells how CSS class names are transformed.

   The JSON object is something like followings.

   {
     "title": "_title_xkpkl_5 _title_116zl_1",
     "article": "_article_xkpkl_10",
   }

   If using webpack, it can be obtained by setting modules option of css-loader. Please see webpack.config.js and src/index.js files of example apps.

2. Pass the JSON object to Elm via flags

3. Decode the JSON object by CssClass.decode : Decoder CssClass on the Elm side

4. Use class : CssClass -> String -> Attribute msg to specify CSS class name to append

   It internally searches transformed CSS class name for the class name, and set the transformed name to the element.

It is not necessary, but using arowM/elm-html-with-context helps to pass CssClass value to each view function without explicitly passing it as an argument.

Examples

Example apps are in examples directory.

• examples/simple: An example project shows basic usage of this library
• examples/real-world: An example project shows how to use this library in large projects by integrated with elm-html-with-context

Why CSS modules?

Using rtfeldman/elm-css is one of the ways to integrate CSS with Elm. The main strategy of elm-css is writing inline style as an Elm code, but there are defeats about the strategy.

1. Inline style cannot handle CSS specific features such as media queries, pseudo classes, etc...

2. Writing style as an Elm code means it cannot use great tool chains of CSS such as Sass, auto-prefixer, flexbugs-fixes, etc...

3. Type safe is a sort of superfluity for styles

   Almost all styles are checked by eyes, so type safe manner does not give us as much benefits as program codes. In spite of such week benefits, by forcing to use type safe property names decreases productivity.

4. Styles can be shared only between Elm codes

   If your project eventually introducing Elm, it's a pain to translate CSS to Elm (or Elm to CSS).

CSS modules is actually just a CSS file, so there are no defeats that elm-css has.

Of course, elm-css is a great tool in the term of the way to do all the things in Elm, but if your team is familiar with modern CSS tool chains, CSS modules is suitable for you.

Why not elm-css-modules-loader?

The elm-css-modules-loader does hacks to rewrite JS file generated by Elm compiler. One of the actual problems occurred by such hacks is the problem that it cannot be used with elm-hot-webpack-loader. It seems elm-hot-webpack-loader fails because elm-css-modules-loader rewrite generated JS. Another problem is that it cannot be guaranteed to be able to use when Elm compiler changes its behaviour. (In fact, it took a time to elm-css-modules-loader support Elm 0.19. It could be happened on bug fixes of the Elm compiler.)

The other demerit of elm-css-modules-loader is its bothering API that force developers to write which CSS class to use as follows. Boo!

common :
    CssModules.Helpers
        { foo : String
        , bar : String
        , baz : String
        ...
        }
        msg
common =
    css "../../styles/common.scss"
        { foo = ""
        , bar = ""
        , baz = ""
        ...
        }

The elm-css-modules-helper does not have such defeats because it just provide functions to handle JSON object generated by CSS modules that tells how CSS class names are transformed. There are no need to declare all the CSS class names to use in boring style, it just requires developers to specify CSS class names as String.

Wait! Do you realy need this library?

Check example/no-flags. It does not use elm-css-modules-helper nor elm-html-with-context. What the example doing is just setting localIdentName option of css-loader to specify how class names are transformed. In which way, transformed class names are all predictable, so only way to do in Elm side is just converting class names as the specified rules.