Real World Halogen

PureScript is a delightful purely-functional language that offers powerful, pragmatic tools to manage complexity and help you design, build, and refactor reliable apps of any size. This repository demonstrates the principles I apply at work every day in more than 2,000 lines of thoroughly commented code and has an accompanying long-form guide to building real-world Halogen applications.

Using Halogen 4? Browse the repository at the tag for Halogen 4. Upgrading from Halogen 4 to Halogen 5? See the PR which migrated this repository to Halogen 5.

I’m a senior software engineer at Awake Security (and previously at CitizenNet). Both companies have large production PureScript applications that have remained reliable, understandable, and maintainable as they scale. PureScript is an incredible language for building single-page applications.

This repository follows the RealWorld spec to implement a Medium clone called Conduit using Halogen. It’s large enough to demonstrate real world examples (CRUD, state management, scalable architecture, type classes, components, etc.) but not so large as to be overwhelming.

If you have found this repository and the guide useful, please consider becoming a sponsor!

Installation

First, clone the repository:

git clone https://github.com/thomashoneyman/purescript-halogen-realworld
cd purescript-halogen-realworld

You can enter a development shell with all non-JavaScript dependencies via Nix:

nix-shell

Alternately, you can install PureScript, Spago, and Zephyr manually. You can use NPM to install PureScript and Spago, and you can install the Zephyr binary from its releases page -- ensure it exists in your PATH by moving it to usr/bin/local.

Next, install JavaScript dependencies:

npm install

Building and running

Next, build the project (this command will run spago build; see the package.json file to see all helper scripts for the project):

npm run build

You can bundle the JS for production:

npm run bundle

And, once bundled, you can run a local server to use Conduit (defaults to port 8080, but if this port is already in use it will increment to 8081, etc.):

npm run serve

Dev mode

To run it in dev mode where saving your changes rebuilds and reloads the app, you can run the command below (which calls spago build --watch)

npm run watch

And run the application with

npm run serve-dev

This will open your default browser at port 1234

Learning PureScript

This project is intended to give non-PureScript developers a taste of what a small application in the language looks like, and to give advanced beginners in PureScript a resource to feel comfortable building reliable applications of their own.

PureScript is a delightful language that becomes only more interesting and rewarding the more you use it and the larger your application becomes; if you haven’t yet tried it out, I encourage you to do so. Not convinced? Kris Jenkins has a lovely talk about PureScript which might change your mind.

Resources

The PureScript community is overwhelmingly warm and helpful. If you would like some help getting started, please consider joining the official Discourse and functional programming Slack (invite link). You may also want to check out:

1. PureScript by Example, which will teach you PureScript from scratch and was written by the language’s creator, Phil Freeman. While the official book has not been updated for the latest version of the compiler, this link is to an up-to-date fork of the book.
2. Jordan Martinez’s PureScript reference, which has a broad overview of dozens of topics in PureScript and functional programming.
3. The (warning: currently in rough draft form) handbook which explains the theory & principles at work in this application in-depth, which will be useful to help take you from advanced beginner to advanced intermediate in the language.
4. The official Halogen guide, which will teach you how to use the Halogen framework to write components.

Contributing

PRs are welcome! Any functional changes will need to remain compliant with the RealWorld spec, and I may re-word documentation changes to fit with the voice used throughout the repository.