There is now a version of this guide for 2021:
https://discourse.purescript.org/t/recommended-tooling-for-purescript-in-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!
Recommended Tools
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 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.
You can install these tools with npm
or via Nix with easy-purescript-nix
. If your project is PureScript-only then you don’t need anything else. Even so, I recommend also considering:
-
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 purescript-slug library is an example of a project built using only these tools (including CI). However, a typical PureScript application will also use some JavaScript libraries and tools. In that case, I recommend some tools from the JavaScript world:
-
npm
, the default JavaScript package manager that ships with Node. It’s used to install JavaScript libraries and tools (and PureScript tooling, if you want) and to run scripts via apackage.json
file. -
parcel
, a bundler for JavaScript. It’s used to bundle, minify, and optimize all of your project’s JavaScript (including your compiled PureScript code) together into a single file that can be run in the browser or on Node. A bundler is not necessary for PureScript-only projects, but it /is/ necessary for projects that include both PureScript and JavaScript.
The Halogen library uses NPM and a package.json
file to install PureScript tooling and run scripts. It can be useful to do this even if you have no JavaScript code or dependencies.
The official Halogen template project and unofficial React Basic Hooks template project install a bundler via NPM and use the package.json
file as a script runner.
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.
The Real World Halogen application is an example of a PureScript application built using all of these tools — including continuous integration via setup-purescript
.
Other Recommended Tools
There are many other tools in the PureScript ecosystem worth exploring. These are ones I recommend checking out first:
-
purty
is 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. -
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.
Using Nix
If you are a Nix user, you can set up a PureScript tool chain and generate Nix derivations using the following tools:
-
easy-purescript-nix
is 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 providespurs
,spago
,zephyr
,purty
,psa
, and many other tools at multiple versions via Nix. -
yarn2nix
andspago2nix
can be used to generate Nix derivations for your JavaScript and PureScript dependencies in Nix.
Libraries like Halogen Hooks use a Nix shell for development dependencies. There is also an example project by @tbenst which uses these tools to build a Halogen application with Nix.
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
JavaScript Tools
There are some tools from JavaScript useful in a typical PureScript project – I won’t go in depth, but these are a starting point for exploring further:
-
webpack
(optionally withpurs-loader
) andparcel
are a few of the many tools you can use to bundle and minify assets like JavaScript and CSS in your web projects. PureScript produces JavaScript, so most of these tools work fine on your compiled code. Some tools rely on ES modules, which PureScript doesn’t yet produce, and so you won’t be able to use them on your compiled output. -
eslint
andjsconfig.json
are useful for linting your JavaScript FFI code. -
npm
,yarn
, andpnpm
are a few of the many package managers available for JavaScript. By default I recommend usingnpm
, but there are many alternatives out there.