Home

Awesome

Try PureScript

Build Status

Try PureScript is an online PureScript code editor for quickly experimenting with PureScript code snippets and ideas. It consists of a client and a server component, both of which live within this repository.

Features:

Control Features via the Query String

Most of these features can be controlled not only from the toolbar, but also using the query parameters:

Which Libraries Are Available?

Try PureScript aims to provide a complete, recent package set from https://github.com/purescript/package-sets. The available libraries are those listed in staging/spago.dhall, at the versions in the package set mentioned in staging/packages.dhall.

Development

1. Shared setup

These steps should be performed whether you are working on the server, the client, or both.

# Clone into the repository
git clone git@github.com:purescript/trypurescript.git
cd trypurescript

2. Local compile server setup

This step sets up a local server for Try PureScript. You can skip this step if you just want to use the client with the production server.

# Build the trypurescript executable
stack build

# Set up the PureScript environment for the server
cd staging
spago build

# Ensure the compiled JavaScript is available to the client via symbolic link.
ln -s "$PWD/output" "$PWD/../client/public/js/output"

# Then, start the server.
#
# Below, we disable glob expansion via `set -o noglob` to ensure that globs are
# passed to `purs` unchanged.
#
# We run this in a subshell so that setting noglob only lasts for the duration
# of the command and no longer.
(set -o noglob && stack exec trypurescript 8081 $(spago sources))

# Should output that it is compiling the sources (first time)
# Then: Setting phasers to stun... (port 8081) (ctrl-c to quit)

3. Client setup

# Install development dependencies
cd client
npm install

# Use `serve:dev` if you are using a local Try PureScript server,
# e.g. you followed the instructions in step 1.
#
# Use `serve:production` if you would like
# to test the client against the production Try PureScript server.
# Note: the production server may not match the package set you have locally.
npm run serve:(dev|production)

# Try PureScript is now available on localhost:8080

4. Choosing a Tag

The built-in examples for Try PureScript are loaded from this GitHub repository. To change the tag that the examples are loaded from, you'll need to touch three files:

If you are preparing a release or if you need to adjust examples in development, you should change the tag in these three places (and ensure you're using the same tag in each place!).

Server API

The server is a very basic web service which wraps the PureScript compiler, allowing clients to send PureScript code to be compiled and receiving either compiled JS or error messages in response. It is hosted at https://compile.purescript.org/.

Compile PureScript code

POST /compile

Response body on compilation success:

{
  "js": "...", // a string containing JavaScript code
  "warnings": [ ... ] // an array of warnings, using the same format as the
                      // compiler's --json-errors flag
}

Response body on compilation failure:

{
  "error": {
    "tag": "CompilerErrors",
    "contents": [ ... ] // an array of errors, using the same format as the
                        // compiler's --json-errors flag
  }
}

Response body on other errors (eg, the name of the module in request body was not Main, or the request body was too large)

{
  "error": {
    "tag": "OtherError",
    "contents": "..." // a string containing an error message
  }
}

Note that the API returns a 200 response in all of the above cases; in particular, if the code in the request body fails to compile and the API returns errors, this is still considered a success. Among other things, this makes it easier to use the API from another domain using CORS.

The output code will contain references to any imported modules using require calls. To run these files in the browser, it is necessary to either use a require shim (such as require1k), or replace these calls and deploy a bundle of precompiled modules. The Try PureScript client uses the first approach.

GET /output/:module/(index.js|foreign.js)

The server exposes the compiled JS for all of the modules it has access to. If the compiled JavaScript code in the response includes a require call such as require(../Web.HTML/index.js), then the client is expected to arrange things so that this require call provides access to the JavaScript code available at the URL path /output/Web.HTML/index.js, via a shim or otherwise.

Configuration

The server application takes the following arguments on the command line:

Example

trypurescript 8081 'bower_components/purescript-*/src/**/*.purs'