If you do it three times it’s a tradition – welcome to the annual ‘Recommended Tooling for PureScript’ post! Thanks to @eikooc for reminding me to make an update. As usual, all opinions are my own. You can see previous years here:
Changes This Year
The most notable new tools for PureScript are two new formatters, both written in PureScript using the language-cst-parser
library by @natefaubion.
-
purs-tidy
is my personal choice among PureScript formatters. It supports several useful options like arrow-first (the most common style) or arrow-last (purty
-style) formatting, as well as the ability to group operators by precedence when formatting. -
pose
is a PureScript port ofpurty
(purty
is not compatible with PureScript 0.14). It’s in low-maintenance mode and is a good option for folks who prefer thepurty
formatting style, but for most users I’d recommendpurs-tidy
instead.
There have also been some notable tools released as libraries, not standalone tools:
-
tidy-codegen
is a library for generating PureScript modules (we use this at Awake Security to generate our API!).
Example Projects
As usual, you can see examples of the tools I recommend in action in these repositories:
- Real World Halogen by @thomashoneyman
- Real World PureScript React by @jonas
- The PureScript Cookbook by @jordanmartinez, @ptrfrncsmrph, @milesfrain and others
There are also a few new excellent example projects this year, including:
-
Real World PureScript Payload by @jim, which demonstrates PureScript on the backend with the
payload
library. - Halogen Extended Template by @and-pete, which builds on the default Halogen template with common libraries used in Halogen apps.
Installing Tools
You can install PureScript tools (like purs
) either system-wide or in a particular project using one or more methods, listed in order of popularity:
- Use a package manager that uses the NPM registry, such as
npm
- Use the Nix package manager via
easy-purescript-nix
If you use GitHub Actions, then you can use the setup-purescript
GitHub Action to set up a PureScript toolchain on Windows, macOS, or Linux in your workflow.
Recommended Tools
If you are starting a new project in PureScript today, you will need at minimum:
-
purs
, the compiler. Spago usespurs
under the hood to compile your code, start an interactive repl, and so on. The compiler also provides an IDE server for editors to use. -
spago
, the build tool and package manager for PureScript. It’s used to install PureScript libraries, build PureScript code, generate documentation, and bundle PureScript-only applications.
While not necessary, I also recommend these tools for most projects:
-
psa
is a configurable error-reporting frontend for the compiler. It lets you control reporting for errors and warnings. Spago automatically usespsa
if it is available in your PATH. -
pscid
is 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 building a PureScript application, you may also like:
-
zephyr
is 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.
If your application includes any JavaScript dependencies, then you are also going to need some JavaScript tools to make your code work. Specifically, you’ll want to have:
- A JavaScript package manager for installing JavaScript dependencies, such as
npm
,yarn
, orpnpm
. I recommend using NPM. - A JavaScript bundler for including your JavaScript dependencies in your bundled PureScript code, such as
webpack
,parcel
, oresbuild
. I recommendesbuild
for simple projects andwebpack
for more complex ones. - You may also want to use a linter like
eslint
to help check your JavaScript FFI code.
Editor support
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 forpurty
). - Vim with
purescript-vim
,psc-ide-vim
, and/orcoc.nvim
for IDE features. Also see the Vim IDE options Discourse thread. - Emacs with
purescript-mode
andpsc-ide-emacs
Wrapping Up
I’ve kept the post nice and short this year! If you have any suggestions for other notable new tools or example projects using these tools that I should include, please let me know and I can edit the post. Thanks for reading!