# elm-css-modules-helper

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

[![sakura-chan-eating-corn](https://user-images.githubusercontent.com/1481749/46577944-349f6300-ca2d-11e8-92bd-c5efbdc9a13b.jpg)](https://twitter.com/hashtag/%E3%81%95%E3%81%8F%E3%82%89%E3%81%A1%E3%82%83%E3%82%93%E6%97%A5%E8%A8%98?src=hash)

## What is this?

This is an Elm library making it easy to use [CSS modules](https://github.com/css-modules/css-modules) in Elm.

There are [cultureamp/elm-css-modules-loader](https://github.com/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.

    ```json
    {
      "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`](https://github.com/webpack-contrib/css-loader#modules).
    Please see `webpack.config.js` and `src/index.js` files of [example apps](https://github.com/arowM/elm-css-modules-helper/tree/master/examples).

1. Pass the JSON object to Elm via flags
1. Decode the JSON object by `CssClass.decode : Decoder CssClass` on the Elm side
1. 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`](https://github.com/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](https://github.com/arowM/elm-css-modules-helper/tree/master/examples).

* `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](https://github.com/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...
1. Writing style as an Elm code means it cannot use great tool chains of CSS such as Sass, auto-prefixer, flexbugs-fixes, etc...
1. 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.

1. 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!

```elm
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`.