purs-nix

purs-nix is a tool for Nix-based PureScript development. It comes with both a Nix API, as well as a CLI you can use for development.

This project is currently unstable. That being said, most of the current API has been stable for some time, and we try to maintain backwards compatibility when introducing new APIs if possible.

Gettings Started

• Setup nix.
• Run nix flake init -t github:purs-nix/purs-nix in a new directory to initialize a new project.
• Run nix develop to enter a Nix shell with the purs-nix command added to your PATH.
• Run purs-nix run to see the output of the default project.

Getting Started (non-flakes)

• Install Nix
• Copy the template from templates/default, and then replace flake.nix with templates/shell.nix.
• Run nix-shell to enter a Nix shell with the purs-nix command added to your PATH.
• Run purs-nix run to see the output of the default project.

Learn

• Documentation

• Examples

Package Set

purs-nix has its own package set, which is an extension of the the official package set with the following differences:

• Package namespaces: We have package namespaces.

• No global module namespace: All packages are not required to compile with each other.

• Single source of truth for package info: You can define the version and dependencies of your package in its home repository and import it here. Nix is lazy so you will only ever download the information for the packages you need.

• Packaging Foreign Dependencies: purs-nix allows you to bundle Node.js (or arbitrary JavaScript code) in with your package so it'll work for people without them having to manage external dependencies.

• Easy modification: Using a modified version of the package set is as easy as forking it and changing the input of your flake ("github:purs-nix/purs-nix" -> "github:<your-username>/purs-nix"). If you put in a PR to add your package, using your fork of the package set is just as easy as using the official one, so you don't have to wait for the PR to be accepted to use your normal workflow.

• Get package info: Since package info can be imported from a foreign repository, we need a way to view the info of a package easily.

  • To view the info of a package, use nix run github:purs-nix/purs-nix#package-info.<package-name>. (a namespaced package will need to have quotes around its name, as it contains a .. You can do that like this: .#package-info.'"<namespace>.<name>"'.)

Updating

To update the purs-nix package set:

$ cd official-package-set
$ ./generate.sh

Migrating from spago

There is a difference in the default esbuild format used by purs-nix and spago. The default used by purs-nix is ESM format. The default used by spago bundle-app is IIFE format. To match spago, specify bundle.esbuild.format = "iife", i.e.:

...
bundle =
  { ...
    esbuild = { format = "iife"; };
  }
...

Contributing / Mirrors

Bug reports and patches are always welcome. Feature requests and new features are also welcome, but please consider discussing them with the maintainer first.

You can contribute through GitHub or Codeberg.

To set up these mirrors as push remotes for origin

$ git remote set-url --add --push origin git@github.com:purs-nix/purs-nix.git
$ git remote set-url --add --push origin git@codeberg.org:purs-nix/purs-nix.git

And pull

$ git fetch --all

Actively Maintained

This project is actively maintained by Platonic.Systems