elm-wrap — Local Dev

Local dev mode is elm-wrap's star feature: it lets you pretend that your package under development is already published and installed in ELM_HOME. That in turn lets you install the package in your example app (or apps!) without having to do the awkward modifications of source-directories in every app you want to test your package with.

If you are into organizing your code into packages, this is the power tool for you!

Let's walk through a simple example.

Set up a new package

Say we want to develop a new package from scratch. We'll initialize a package and an example app to develop in parallel so that we can exercise the package API.

$ cd projects
$ mkdir pkg example-app
$ cd pkg
$ wrap package init my/pkg # This command creates a package and makes it available for local development
$ cd ../example-app
$ wrap application init
# We now have the application installed, let's add our package
$ wrap install my/pkg
# That's it! The package is now installed
$ wrap application info -d

Dependencies:

  elm/browser      1.0.2
  elm/core         1.0.5
  elm/html         1.0.1
  elm/url          1.0.0
  my/pkg           1.0.0 # 👈 there it is!

Working with existing package sources

Say we already have some package under development. We need to register it with our apps, and then we'll be able to do what we did for a new package.

There are two ways to do it. While it's usually better to have only one way of doing things, having symmetry is nice.

First, we can do a similar thing we did for the new package: enroll it into local dev tracking.

$ cd projects/existing-pkg
$ wrap install --local-dev my/existing-pkg
# At this point, the package is in local dev and behaves like any other published package
$ cd ../example-app
$ wrap install my/existing-pkg
# Just like we're used to!
# Even elm install my/existing-pkg should work here

The other way is symmetrical: add the package from the app and enroll it in local dev at the same time. Without visiting the package source directory, we can just install it in the app:

$ cd projects/example-app
$ wrap install --local-dev --from-path=../existing-pkg my/existing-pkg
# That's it! The package is now in our elm.json and we can just work with it.

From this point we can either update the package code or the app, and wrap make will ensure the package appears as new to the Elm compiler, making it recompile the package.

If you had your elm.json with source-directories pointing to ../existing-pkg, now is the time to remove it! Otherwise you'll see compiler errors about duplicate modules from your package.

Building

Once we set things up, we can proceed with development as usual. Edit the package a bit, and run wrap make src/Main.elm in the example app folder, as you usually would.

$ wrap make src/Main.elm

All dependencies cached. Running elm make...

Dependencies ready!
Success! Compiled 1 module.

    Main ───> index.html

What's the status

wrap does its best to always show you the status of local dev packages. For example, application info will tell you if the app is using any local dev packages. Simply run wrap application info in the application's source directory:

$ wrap application info

example-app
-------------------

Type: Application
Path: /Projects/example-app

Dependencies:

  elm/browser      1.0.2
  elm/core         1.0.5
  elm/html         1.0.1
  elm/url          1.0.0
  my/pkg           1.0.0

  elm/json         1.1.4 (indirect)
  elm/time         1.0.0 (indirect)
  elm/virtual-dom  1.0.5 (indirect)

  Total:           8

No upgrades available. All packages at their latest version


Tracking local dev packages:

  my/pkg 1.0.0

Note the "Tracking local dev packages:" line at the bottom.

If after a while you want to see all packages participating in local dev, the repository command group has a command for that:

$ wrap repository local-dev
Tracked local-dev packages:

  my/pkg 1.0.0
    -> /Projects/example-app/elm.json

  my/existing-pkg 1.1.0
    -> /Projects/example-app/elm.json

Will this lead to more low quality packages, like npm?

No. Local dev just makes things simpler for those that already develop quality packages. Nothing with this feature motivates people to do low-quality packages, or to pump out more. If anything, there will be less errors in published packages and example applications, and less rapid patch updates in the registry.

When elm-wrap's vision of "professional code management" becomes reality with private repositories and curation policies, the number of packages in the public registry will go down. Anyone wanting to reuse their code for their own needs will have a proper private repository, and will not need to push packages into the public registry just to benefit from this form of code management.