README.md

generator-elm

Generate a minimal Elm + Webpack 4 project.

$ yo elm my-app
$ cd my-app
$ npm start
./src/Main.elm served at <http://localhost:3000>

Features

• Hot reloading: On file save, the app is updated without resetting your Elm models.
• Sass support: Just write some .scss files.
• CSS vendor autoprefixing: Automatically adds prefixes like -webkit to your styles when necessary.
• Modern Javascript: Write ES6 and it'll be compiled to ES5.
• ESLint: Includes a basic .eslintrc and an npm run lint command.
• Gzip: Production builds generate dist/main-{js,css}.gz files alongside the uncompressed files.

Install

Install Yeoman (generator framework) and generator-elm globally:

$ npm install -g yo generator-elm

Generate

Generate scaffolding in a target folder (created if it does not exist):

$ yo elm <destinationFolder>

Or in the current folder:

$ yo elm .

Skip the NPM + Elm installs after generation:

$ yo elm my-app --skip-install

Run

Development

Start the local hot-reloading development server and visit http://localhost:3000.

$ npm start

Or start the dev server on a custom port:

$ PORT=8080 npm start

Production

Bundle the app into a dist folder ready to be deployed.

$ npm run build

.
└── dist
    ├── index.html
    ├── 60b725f10c9c85c70d97.css
    ├── 5df766af1ced8ff1fe0a.js
    └── img
        └── ...

It's useful to serve the built dist folder locally for debugging or sanity-checking:

$ npm install -g serve
$ serve dist
Serving dist at http://localhost:5000

Anatomy of the Scaffolding

Here's the generated project folder:

.
├── README.md          # for your personal use, notes
├── elm-package.json   # elm's deps
├── package.json       # webpack's deps, implements the `npm` commands
├── webpack.config.js
├── src                # your elm code/components go in here
│   ├── Main.elm       # root elm component, begin hacking here
│   └── index.js       # root javascript file, webpack entrypoint
├── public
│   ├── index.html     # root html file, Main.elm mounts to it
│   ├── favicon.ico    # a default favicon for you to replace
│   ├── css
│   │   └── index.scss # root css file that should @import other css files
│   └── img
│       └── elm.png
└── dist               # the stand-alone folder generated by `npm run build`
    ├── index.html     # throw the contents on a server and open index.html
    ├── main-<hash>.js
    ├── main-<hash>.css
    └── img
        └── ...

Using Travis CI

TODO: This section has not been updated / checked since the migration to Webpack 4.

We took the liberty to include a .travis.yml file. But you will need to change your webpack config to run it in a performant way. First let's install a new package:

npm install --save-dev global-prefix

Then import it in your webpack.config.js:

const prefix = require('global-prefix')

You want to remove the following from the common part of your config:

      {
        test: /\.elm$/,
        exclude: [/elm-stuff/, /node_modules/],
        use: ['elm-webpack-loader'],
      },

And copy it to both the development and your production config, right after the plugins element. Then change your production config to the following code block, if production is the config travis should use.

    module: {
      rules: [
        {
          test: /\.elm$/,
          exclude: [/elm-stuff/, /node_modules/],
          use: ['elm-hot-loader', 'elm-webpack-loader?verbose=true&warn=true&pathToMake=' + prefix + '/bin/elm-make'],
        },
      ],
    }

That's it, make sure to customize your .travis.yml to your needs.

Changelog

• 2018 Aug 26 (v0.0.33):
  • Migrated from Webpack 3 to Webpack 4.

License

MIT © Dan Neumann