There is now a version of this guide for 2021:
Last year I wrote Recommended tooling for PureScript applications in 2019, which is commonly used as a reference for folks setting up PureScript projects. In the last year a few things have changed, including:
- Yarn 2 can’t be used to install tooling like the PureScript compiler and NPM has improved a lot in the last couple of years, so I now suggest returning to NPM by default.
- GitHub Actions has become a fantastic option for CI, and there’s now setup-purescript to get a full PureScript toolchain in CI without requiring Node, so I’ve added a note on CI.
- The community has standardized more on a set of common tools, and in response I’ve trimmed the list of tools to just ones I would recommend.
- There are many more example PureScript applications built with React, Halogen, or another framework, or set up via the PureScript Cookbook or various templates. It’s been a great year for access to more examples. With this in mind, I no longer included the project setup guide from last year’s post (but it’s still there if you want it). I’ve sprinkled some links through this post.
As with last year: the Real World Halogen application is built using the tools described in this post and is a great starting point to see how a typical PureScript project might be set up. This year there’s also Real World PureScript React as an example!
If you are starting a new project in PureScript today, you will at least need:
spago, the build tool and package manager for PureScript. It’s used to install PureScript libraries, build PureScript code, generate documentation, bundle PureScript applications or modules into a single file, and perform other miscellaneous tasks.
purs, the compiler. Spago uses
pursunder the hood to compile your code, start an interactive repl, and so on. The compiler also provides an IDE server for editors to use.
psa, a configurable error-reporting frontend for the compiler. It lets you control reporting for errors and warnings, and Spago uses this tool automatically if it is installed.
setup-purescript, a GitHub Action to set up a PureScript toolchain for continuous integration. It lets you set up CI on Windows, macOS, and/or Linux with common PureScript tools including the compiler and Spago (among others).
The Halogen library uses NPM and a
If you’re building an application then you will probably want to run an extra dead code elimination step on your PureScript code before bundling it. In that case, I recommend also including:
zephyr, a dead code elimination tool for PureScript. It’s used to remove unused PureScript code before compiling the result in order to trim bundle sizes. It’s not used in libraries, but it’s common in PureScript applications.
There are many other tools in the PureScript ecosystem worth exploring. These are ones I recommend checking out first:
purtyis a source code formatter for PureScript. It’s used to standardize the style of PureScript code, which means less mental energy spent tweaking style and smaller diffs when reviewing code.
pscidis a /fast/ file watcher that reports errors and suggestions in the shell. It’s essentially the same as the error reporting provided by your editor, but can often be faster.
If you are a Nix user, you can set up a PureScript tool chain and generate Nix derivations using the following tools:
easy-purescript-nixis a one-stop-shop for installing tools for PureScript in Nix. It’s often used to produce developer shells or to write a derivation to build your whole PureScript project in Nix. It provides
psa, and many other tools at multiple versions via Nix.
The PureScript compiler has an IDE server included, which has been used to implement a PureScript language server that major editors can use. Some of the features that PureScript’s IDE tooling supports include:
- Auto-completion, definitions & documentation on hover, and jump-to-definition
- Automatically fix imports, missing types, and other compiler errors / warnings
- Fast rebuilds on file save
- …many more!
Most folks I know writing PureScript use:
- VSCode with
ide-purescript(there is also a plugin for
- Vim with
coc.nvimfor IDE features. Also see the Vim IDE options Discourse thread.
- Emacs with
npm, but there are many alternatives out there.