README.md

frontend-elm-kit

A set of tools and integrations used by our Elm applications.

Installing

Adding to a new project? Create a .npmrc file in its root with the following content:

@PaackEng:registry=https://npm.pkg.github.com

First time installing a private npm package from Paack's Github? Setup your token.

Once the above is done, just install it:

$ yarn add @PaackEng/frontend-elm-kit

Add it as a source directory in the elm.json:

"type": "application",
"source-directories": [
  "src",
+ "node_modules/@PaackEng/frontend-elm-kit/elm"
],

Integrating

In order to integrate this package into your project there are some extra changes that need to be made:

• Install all the required packages with exception of elm/html
• Make sure that the modules Data.Environment, Main.Model, Main.Msg, Main.Update, Effects.Local and Effects.Performer all exist. Look at the example folder for a minimal setup
• If you're using parcel v1 disable sourcemaps with --no-source-maps

Auth0

• Ensure that the ports checkSession, login and logout are all present
• Provide all the four seeds (randomSeed1, 2, 3 and 4) in the app's Flags
• Install the Auth0 SPA SDK
• If your application isn't using Effect yet you can use Auth.performEffects to convert them on the fly. Otherwise, it's recommended to use Effects.MainHelper

Firebase

• Install the Firebase JavaScript SDK
• Initialize firebase with your Firebase project configuration

Rollbar

• Make sure your model includes appConfig.environment. codeVersion, rollbarToken and url;
• You'll need a message for receiving feedback, see how the example performs the effect;

Mixpanel

• Provide the two flags mixpanelToken and mixpanelAnonId which should be saved to the localStorage;

Extending configuration

This package provides default configuration for Eslint, Prettier and TypeScript. Here's how to extend the config:

.eslintrc.json

{
+  "extends": "./node_modules/@PaackEng/frontend-elm-kit/eslintconfig.json"
}

package.json

  "name": "lmo-web",
  "version": "1.0.0",
  "description": "Last-Mile Operations",
+ "prettier": "@PaackEng/frontend-elm-kit/prettier",

tsconfig.json

{
+  "extends": "@PaackEng/frontend-elm-kit/tsconfig.json",
+  "include": ["web/ts"]
}

Suggestions

Rollbar

• Don't forget to update the url value in model when it changes;
• Compose errors with Paack.Rollbar module;
• Easy transform Http errors with Paack.Rollbar.Http module;
• Easy transform Graphql errors with Paack.Rollbar.Graphql module;
• Produce the effect with Paack.Rollbar.Dispatch.

Deploying

Bump the version according to the change that was made. Once it's merged to main just push a tag in the format v*.*.*.

  "name": "@PaackEng/frontend-elm-kit",
- "version": "0.0.3",
+ "version": "1.0.0",

$ git tag -a v1.0.0 -m "First version"
$ git push --tags

Running the example

Navigate to the example folder, then create a .env file and fill in the values (you can copy them from any project where Auth0 is configured). After that you can run it with yarn start.