Welcome to the annual ‘Recommended Tooling for PureScript’ post! You can see previous years here:
- Recommended tooling for PureScript in 2021
- Recommended tooling for PureScript in 2020
- Recommended tooling for PureScript in 2019
Changes This Year
There are two notable new tools for PureScript this year:
-
purescript-backend-optimizer
is a new optimizing backend toolkit for PureScript, which ships with its own ECMAScript code generator that generates more readable, modern code than the compiler. It produces code up to 35% faster and 25% smaller than thepurs
compiler alone. Development was lead by @natefaubion. - The PureScript Registry entered alpha this year. It stores PureScript packages and metadata about them, produces package sets, and provides a library to help authors of package managers integrate with the various registry components. The PureScript registry is a replacement for the Bower registry and offers much better support for publishing PureScript packages. When you publish your package to the PureScript Registry its documentation is uploaded to Pursuit and it is added to the day’s package sets release automatically.
While it’s not a new tool, I must also mention that PureScript 0.15 was released this year, bringing support for ES modules to PureScript. This has opened PureScript projects plenty of new JavaScript build tooling, such as esbuild
, vite
, and other dev tools that require ES modules. Notably, purs
no longer supplies a bundler, which means you must now use a JavaScript bundler such as esbuild
. This is good news: bundle sizes are about 25% smaller with the new compiler output + esbuild
!
Example Projects
As usual, you can see examples of the tools I recommend in action in these repositories:
- Real World Halogen by @thomashoneyman, which demonstrates PureScript using the Halogen UI library.
- Real World PureScript React by @jonas, which is the same project as Real World Halogen, except written using React bindings.
- The PureScript Cookbook by @jordanmartinez, @ptrfrncsmrph, @milesfrain and others, which demonstrates how to write common snippets of PureScript code.
-
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
orpurs-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, and generate documentation.
If you are building an application for the browser, you will also need:
-
esbuild
, a bundler and build tool for JavaScript. Spago will useesbuild
to bundle your code when you runspago bundle-app
, ifesbuild
is installed.
While not necessary, these tools are also useful in many projects:
-
purs-tidy
is by far the most popular code formatter for PureScript. -
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. -
purescript-backend-optimizer
is an optimizing backend toolkit for PureScript, which produces code up to 35% faster and 25% smaller thanpurs
alone. It should be used when bundling PureScript for production.
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
- Vim with
purescript-vim
and eitherpsc-ide-vim
or a LSP plugin. - Emacs with
purescript-mode
and eitherpsc-ide-emacs
or a LSP plugin
Library Authors
If you are authoring a library that you plan to publish to the PureScript Registry, with documentation published to Pursuit, then you have historically been forced to use the Bower package manager and Pulp build tool instead of Spago. While you can continue to use these tools, you no longer have to. Now that the registry is in alpha you can publish Spago projects so long as all of your dependencies point to valid SemVer Git tags (and not, for example, to a branch like main
or a particular commit).
To learn more, please see the registry alpha announcement:
https://discourse.purescript.org/t/registry-alpha-launched
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!