Recommended Tooling for PureScript in 2022

Welcome to the annual ‘Recommended Tooling for PureScript’ post! You can see previous years here:

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 the purs 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:

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:

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 uses purs 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 use esbuild to bundle your code when you run spago bundle-app, if esbuild 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 uses psa 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 than purs 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, or pnpm. I recommend using NPM.
  • A JavaScript bundler for including your JavaScript dependencies in your bundled PureScript code, such as webpack, parcel, or esbuild. I recommend esbuild for simple projects and webpack 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:

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!

25 Likes

If you’re doing projects in Nix, I’d strongly suggest checking out purs-nix.

GitHub Mirror: GitHub - purs-nix/purs-nix: Manage your PureScript projects with Nix!
Codeberg Mirror: purs-nix/purs-nix - purs-nix - Codeberg.org

Monorepo/multi-package support is in the works.

5 Likes