Hop: A router for Elm SPAs

How this works

Matching routes

 ,-------.            ,---.                ,---.
 |History|            |Hop|                |App|
 `---+---'            `-+-'                `-+-'
     |1 location change |                    |  
     |----------------->|                    |  
     |                  |                    |  
     |                  |2 (Route, Location) |  
     |                  |------------------->|  
 ,---+---.            ,-+-.                ,-+-.
 |History|            |Hop|                |App|
 `-------'            `---'                `---'

• Routes are defined as union types e.g. User Int
• You define path matchers e.g. match2 User "/users/ int. This matches a path like /users/1.
• (1) When the browser location changes, Hop will match the path e.g. /users/1 -> User 1.
• (2) Hop provides a signal that you application consumes, this signal carries the matched routes and information about the current location.

Navigation

 ,---.          ,---.              ,---.          ,-------.
 |Elm|          |App|              |Hop|          |History|
 `-+-'          `-+-'              `-+-'          `---+---'
   |              |1 navigateTo path |                |    
   |              |----------------->|                |    
   |              |                  |                |    
   |              |                  | 2 change path  |    
   |              |                  |--------------->|    
   |              |                  |                |    
   |              |                  |   3 Task       |    
   |              |                  |<- - - - - - - -|    
   |              |                  |                |    
   |              |    4 Effects     |                |    
   |              |<- - - - - - - - -|                |    
   |              |                  |                |    
   |   5 Task     |                  |                |    
   |<-------------|                  |                |    
 ,-+-.          ,-+-.              ,-+-.          ,---+---.
 |Elm|          |App|              |Hop|          |History|
 `---'          `---'              `---'          `-------'

• (1-2) To change the browser location you call Hop.Navigate.navigateTo.
• (3-5) This will return an effect that your application must run via ports.
• When the task is run by Elm the browser location changes.

Hop works with StartApp out of the box.

Hash routing

At the moment only hash routes are supported i.e. #/users/1.

Although a proper url should have the query before the hash e.g. ?keyword=Ja#/users/1, in Hop query parameters are appended after the hash path e.g. #/users/1?keyword=Ja. This is done for aesthetics and so the router is fully controlled by the hash fragment.

Docs

Getting Started

Building routes

Navigating

API

Upgrade guide 2.1 to 3.0

Version 2 documentation

Changelog

Examples

See examples. To run the example apps:

• Clone this repo
• Go to example folder (e.g. examples/basic or examples/full)
• Follow the readme in that folder

Testing

cd ./test
elm package install -y
npm i
npm test

TODO:

• Navigate needs functions to:
  • Change path only (without changing the query)
• Navigate without adding to history
• Push state - Support routes without hashes
• Redirects e.g. "/" -> "/dashboard"

Possible improvements

• In order to match the initial route we need to manually send tasks to a port. Done via route.run. This is one more thing for the user to do. Is this really necessary, can this be removed? Maybe in Elm 0.17.

• Remove the need to pass the current url to query methods. At the moment we need to send setQuery location dict because Hop cannot figure out the current query by itself. This project could be the solution.

Acknowledgements

Thanks to @etaque and @Bogdanp for the inspiration to make this better.