Skip to content

Latest commit

 

History

History
141 lines (89 loc) · 9.45 KB

Editor-and-tool-support.md

File metadata and controls

141 lines (89 loc) · 9.45 KB
Raw

Editor and tool support

The PureScript ecosystem contains a number of editor plugins and tools to help you build libraries and applications. The set of available tools is growing continuously, but this documentation contains popular, stable tools that you can use today.

At minimum, almost all projects will use:

These tools can be installed via NPM, among other installation methods.

Which Spago?

At the moment of writing, Spago is going through a period of transition from an older to a new codebase. Consider the following characteristics of each:

Spago

  • The currently maintained and actively developed version of Spago
  • Considered to be in its alpha stage

Spago legacy

  • Officially deprecated and not maintained, except for security updates
  • Considered to be stable
  • A lot of PureScript documentation and guides released pre-2024 would link to the purescript/spago repository while actually having Spago legacy and its API in mind
  • Most PureScript libraries and projects will be using this version for a while

Note that both versions are extensively documented in their respective repositories, consult these if you face any issues. Spago rewrite offers automatic ways of migration from Spago legacy-driven projects.

Editor support

The PureScript compiler includes an IDE server, purs ide, to supply tooling for editors. This server has been used to implement a PureScript language server, which implements the Language Server Protocol for PureScript. Major editor tooling either uses purs ide server directly or via the language server.

Most editor plugins which rely on PureScript's IDE tooling have at least these features:

  • Autocomplete (including auto-imports)
  • Definitions and error reporting on hover
  • Go-to-definition and local search
  • REPL support
  • Automatic builds
  • Error suggestions and quick-fix actions for missing type signatures, imports, and more
  • Case split and holes for type-driven development

General

Some tools are commonly used with several editors, as they are implemented to be editor-agnostic:

  • psa is a pretty, flexible error/warning reporting frontend for the compiler featuring colours, original source spans in errors, warning filtering and persistence.
  • pscid is a lightweight file-watcher and test runner which provides instant-rebuilds in an editor agnostic way.

To generate TAGS files, use purs docs --format etags (or --format ctags).

Atom

Emacs

  • psc-ide-emacs provides editor support via purs ide.
  • purescript-mode provides syntax highlighting and indentation rules for .purs files.
  • psci-mode provides a minor mode for a PureScript REPL.

Spacemacs users can use the PureScript layer.

IntelliJ

  • PureScript plugin provides editor support via purs ide, syntax highlighting for .purs files, and much more.

Sublime Text 3

Vim

  • psc-ide-vim provides editor support via purs ide.
  • ale provides editor support via the PureScript language server.
  • coc.nvim provides editor support via the PureScript language server.
  • purescript-vim provides syntax highlighting and indentation rules for .purs files.
  • vim-lsp-settings provides automatic configuration for editor support via the PureScript language server

VSCode

Tooling support

There are many tools available to help you develop libraries and applications in PureScript. These include build tools, package managers, code formatters, dead code elimination tools, GitHub Actions, Nix tools, and more.

Build tools and package managers

There are several build tools and package managers available for PureScript.

  • spago is the standard package manager and build tool for Purescript.

These build tools are maintained, but are no longer recommended for most projects (use Spago instead):

  • psc-package is a package manager for PureScript based on package-sets and a precursor to Spago.
  • pulp is a standalone build system for PureScript which relies on Bower for package management and a precursor to Spago.

Development tools

  • purescript-backend-optimizer is an optimizing backend toolkit for PureScript's CoreFn and a code-generator which outputs modern ECMAScript.
  • setup-purescript is a GitHub Action which sets up a PureScript toolchain with common tools including the compiler and Spago for continuous integration.
  • purs-tidy is a formatter and pretty-printer for PureScript code.
  • zephyr is a dead code elimination tool for PureScript applications which can be used to reduce bundle sizes.

For Nix users

There are some tools meant specifically for Nix users, who may not be able to use installation methods like NPM.

  • easy-purescript-nix provides many common tools in the PureScript community like the compiler (purs), spago, pscid, zephyr, and more for Nix environments.
  • purs-nix provides support for official package-set, namespaces and overlays on Nix without a external package manager (like spago).
  • purifix package manager in nix using spago (spago.yaml) as single source of truth.
  • spago2nix helps you generate Nix expressions for your Spago dependencies.
  • yarn2nix helps you generate Nix expressions for your JavaScript dependencies.

Backend-specific tooling

PureScript projects which use alternate backends may use tools from the ecosystem of the target language. This documentation is a non-exhaustive starting point for some tools you may find useful when working with particular backends for PureScript.

JavaScript

PureScript projects which target JavaScript may find some tools from the JavaScript ecosystem. PureScript code which imports libraries from JavaScript will at least require a JavaScript package manager (to install dependencies) and a JavaScript bundling tool (to resolve JavaScript imports, among other things). You may also want to use a linter for any JavaScript code you are writing via the FFI.

  • Some popular package managers in JavaScript include npm (recommended), yarn, and pnpm.
  • The recommended way to bundle PureScript code is by using Spago's spago bundle command, which uses esbuild. Other popular bundlers include webpack with the purs-loader PureScript loader, and parcel.
  • Some popular linters include eslint and jsconfig.

Erlang

  • purerlex integrates Purerl code compilation process with BEAM platform's Mix project management tool.

Deprecated and unmaintained tools

These tools were previously mentioned in this documentation, but are no longer maintained or recommended:

  • purty was a PureScript code formatter and pretty-printer.
  • gulp-purescript was a Gulp task for Purescript.
  • psvm-js was a version manager (like nvm for Node) for PureScript compiler versions.
  • psc-pane provided auto-reloading builds which formatted a single error to fit the window.