elm-assets-loader

Elm assets loader

webpack loader for webpackifying asset references in Elm.

Installation

$ npm install --save elm-assets-loader

Usage

Documentation: Using loaders

elm-assets-loader is intended to be chained after elm-webpack-loader, and with a loader to load static assets like file-loader or url-loader.

Suppose we have a union type for tagging asset paths:

module My.Assets exposing (AssetPath(..))

type AssetPath
    = AssetPath String

star =
    AssetPath "star.png"

Tell elm-assets-loader to look for strings tagged with AssetPath:

    loaders: [
      {
        test: /\.elm$/,
        exclude: [/elm-stuff/, /node_modules/],
        loaders: [
          'elm-assets?module=My.Assets&tagger=AssetPath',
          'elm-webpack'
        ]
      },
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        loader: 'file',
        query: {
            name: '[name]-[hash].[ext]'
        }
      }
    ]

Then at runtime, the value of My.Assets.star will be something like AssetPath "star-038a1253d7a9e4682deb72cd68c3a328.png".

Options

tagger (required)

• Example: "AssetPath"
• The "tag" part of a tagged union of shape <tagger> String that's used to tag asset paths in your code.

module (required)

• Example: "My.Assets"
• Module in which the tagged union is defined.

package (optional)

• Example: "NoRedInk/myapp"
• Look for the tagger inside this package. Not needed if the tagger is defined in your main application code.

dynamicRequires (optional)

• Default: "warn"

• Possible values: "error" | "warn" | "ok"

• What to do with dynamically constructed asset paths.

  • "error" - stop processing the file
  • "warn" - emit a warning
  • "ok" - this is expected; say nothing about it

  Dynamic requires is not supported. This option simply controls whether or not to raise an error or skip over expressions like:

  example iconName =
      AssetPath ("icon-" ++ iconName ++ ".png")
  

localPath (optional)

• Function to transform tagged strings to a path that can be resolved by webpack. For example, you may want to tag URL paths, which may not be resolvable to a filesystem path, so that your code works without being webpacked.

  star = AssetPath "/public/images/star.png"
  
  img [ src (toUrl star) ] []
  

  webpack config:

  module.exports = {
    ...
    elmAssetsLoader: {
      localPath: function(url) {
        // transform `url` to a local path that resolves to a file
        return url.replace(/^\/public\//, "")
      }
    },
    fileLoader: {
      publicPath: function(path) {
        // transform `path` to a URL that the web server can understand and serve
        return "/public/" + url;
      }
    }
  }
  

config (optional)

• Default: "elmAssetsLoader"
• Specify the top-level webpack options key under which elm-assets-loader specific options live.

Note

Don't set noParse on .elm files. Otherwise, requires won't be processed.

Under the hood

Let's walk through what happens to the example above when processed by webpack.

This Elm code:

AssetPath "star.png"

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

_user$project$My_Assets$AssetPath("star.png")

elm-assets-loader turns this into:

_user$project$My_Assets$AssetPath(require("star.png"))

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

_user$project$My_Assets$AssetPath(__webpack_require__(30))

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

30:
function(module, exports) {
   module.exports = "star-038a1253d7a9e4682deb72cd68c3a328.png";
}