Throughout your learning process, it will be helpful to ask others for help. The two places this is often done is on PureScript's Discourse forum and its Discord server.
- Register for an account on PureScript's Discord server
- Note: I'll refer to this as PureScript's chatroom throughout this work.
- Register for the Purescript ML forum here
We'll show how to install the following programs:
purescript- the PureScript language & compiler
spago- a dependency manager and build tool for PureScript
- (optional) a formatter for PureScript
parcel- a build tool for bundling a PureScript application into a multiple JS backends (node, browser, electron)
We can install everything using
npm. However, getting
npm is it's own problem. We can either install it manually by downloading
node and installing that. Or we can use
nvm (Node Version Manager) to install it for us and continue from there.
Justin Woo explains how to set up one's environment for the
0.12.x release but has not been updated for two things. First, the PureScript release at the time was
0.12.0 but now
0.13.8 is out. Second, the instructions use
psc-package, a different build tool workflow than the one we'll use here.
If you just want to get things set up ASAP, follow the below summary of his article's instructions (using
spago instead of the other tools). If you want to understand why you should do these commands, read his article here:
- Install Node 14 or greater: https://nodejs.org/en/download/
- Set your npm prefix:
npm set prefix ~/.npm
- Note: this prevents having to use
sudowhen using NPM to install things since it's default prefix is in a place that requires admin privileges
- Note: this prevents having to use
- Set your PATH:
nvmusing their installation instructions
- Verify that the installation was successful via
command -v nvm
nvm. To get the latest
nodeversion, use the command,
nvm install node.
Unlike the manual install,
nvm properly handles the npm prefix for you. So, you don't need to set it yourself.
Once you have installed
npm, we can use it to install everything in one command:
npm i -g firstname.lastname@example.org email@example.com firstname.lastname@example.org
If you want to install a PureScript formatter, refer to their instructions. The history behind these tools will be covered in the
Build Tools folder:
- purs-tidy - A self-contained formatter written in PureScript
- pose - A plugin written in PureScript for the
npm i -g purs-backend-es
The following commands should now work:
purs --version # 0.15.4 spago --version # 0.20.9 esbuild --version # 0.15.7
Once the above has been verified, you can build this project.
First of all, if you haven't yet cloned this project locally, then do so now:
git clone https://github.com/JordanMartinez/purescript-jordans-reference
Then execute the script below which will install, build, and test every folder in this project:
Whenever I make a new release with breaking changes, this script will remove any outdated dependencies, reinstall the correct ones, and rebuild all of the folders' code.
Atom setup instructions:
- Install Atom:
sudo apt-get install atom
- Launch Atom and install the following packages:
The Atom package,
ide-purescript, is configured to
Bower, but we'll be using
spago as our dependency manager for this project. Follow these instructions
- Open Atom's settings dialog (
- Click on the
- Search for
- Click on the
Settingsbutton in the entry that appears
- Check the
Add spago sourcescheckbox
- Change the
spago build -u --json-errors
While this repository's contents are useful for learning various lessons, IDE support (autocomplete, documentation, etc.) will only work if you open this repository's contents in a specific way when using Atom. Follow the instructions below:
- Click "File" and click "Open Folder..." (shortcut:
- In the folder chooser, choose one of this repo's project folders (i.e. a folder with a
- Click on "Packages" and click on "PureScript" and then on "Build". The IDE server will start running and rebuild just that project.*
- Autocomplete, importing, and documentation will now work.
- This is a command you will use frequently, so consider adding a keyboard shortcut for it.
- Open the Atom settings dialog (
- Click on the "KeyBindings" tab
- Click on the "your keymap file" hyperlink that appears before the bindings
- Follow the instructions for adding your personal shortcut for the
For mine, I did:
'.platform-linux atom-workspace atom-text-editor:not([mini])': 'ctrl-shift-b': 'ide-purescript:build'
Sometimes when editing a file, the IDE server will go out-of-sync. For example, you might change the definition of a type and the IDE doesn't realize that occured, so it will tell you that you have used a type incorrectly. In such cases, rebuild the project using Step 3 (or your keyboard shortcut) above and things should correct themselves from there.
In situations where I have used the same names for things, the autocomplete might actually import a function or type with the same name as the one you want but from a different module. So, if you have weird compiler errors, check the imports to insure the IDE server didn't accidentally import something incorrect or from the wrong location.
When you're browsing through code on GitHub, the browser extenstion, Module Linker, can greatly help: https://github.com/fiatjaf/module-linker