How To Publish a PureScript Package (2017): I Wanna Be Pursuit Famous!

Update 2020: This is out of date as you should probably be using spago and creating a spago.dhall file, but pulp publish is still the way to get things into Pursuit. As bower is basically dead, I’m unsure what the future is for Pursuit with this.

Update 2021: A newer guide exists on the PureScript Disourse


I did a quick web search for “publish purescript package” and got no results. I asked a friend, but you may not have that sort of reference at your fingertips. This isn’t meant to be long-winded, but a brief checklist to get you there.


Requirements

  • bower

  • pulp

$ npm install bower pulp

The Must-Haves
  • Pick a licence and add a LICENCE.txt file to your repo and in your bower.json

  • dependencies and devDependencies are in bower.json

  • README

  • Documentation comments

  • It should at least build via pulp build – --censor-lib --strict

The Great-To-Haves
  • Tests in /test/

  • Examples in /examples/


Ready to Publish?

Push a new version tag like this.

$ pulp version
* Checking your package using purs publish...
Dry run completed, no errors.
* The current version is v1.0.0
You can bump the version to:
a) v2.0.0
b) v1.1.0
c) v1.0.1
Choose one, or enter a specific version:

Follow those instructions to get your tag.

Use pulp to publish which will grab the latest version from the repos releases.

$ pulp publish

Congratulations! You have your package published.


More Information on Haves

If you don’t know what licence to pick or don’t really care, BSD-2-Clause is a safe bet. If you don’t care & don’t want your library to endorse products/projects BSD-3-Clause, or 0BSD if you don’t want any restrictions (public domain). However, if you believe in open-source proliferation, consider MPL-2.0 as it means consumers can bundle & vendor your code, but any modifications to any specific file need to also be published as open source. There are stronger copyleft licenses to consider, but the nature of JavaScript bundling makes them harder to recommend. If you need additional advice, consider visiting Write Free Software’s Choosing a license guide.

If your README is Markdown (though any lightweight markup syntax like AsciiDoc, Djot, reStructuredText is renderable) it should at least minimally take a form similar to.

# purescript-package

Your description.

## Installation

```sh-session
$ bower install purescript-package
```

Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-package).

Documentation comments take the form of -- | Comment

-- | This is a test comment for `unit`
foo  Unit
foo = unit

Will publish to Pursuit with the comment “This is a test comment for unit” below the definition. This is super useful for new users of your library to read some plain English when your type is hard to follow or you want to provide addition context. It’s safer to assume that you need documentation rather than not.