Recommended tooling for PureScript applications in 2019

[milesfrain]

I’m a new user working through this guide and two other “official” guides:

• Getting Started
• PureScript by Example: Getting Started (updated fork)

I’ve found this guide to be the most helpful. Should the above two references be updated to follow this workflow?

I’m attempting to update the first guide, and want to clarify what prereqs are needed to launch the repl.

Edit: Found yarn spago repl, so disregard the rest of this message.

Should purescript still be installed with npm or yarn globally, or should I find a way to temporarily add the project’s specific version (located in node_modules/purescript/purs.bin) to $PATH?

Here’s a log of what happens when attempting to launch the repl if purescript is only installed via yarn as described in the first post:

> purs repl
Command 'purs' not found

> node_modules/purescript/purs.bin --version
0.13.3

> node_modules/purescript/purs.bin repl
purs repl: No input files; try running `pulp psci` instead.
For help getting started, visit https://github.com/purescript/documentation/blob/master/guides/PSCi.md
Usage: For basic information, try the `--help' option.

> pulp psci
Command 'pulp' not found

[thomashoneyman]

Yea, looks like the yarn ... commands are what you’re looking for if you want to run locally-installed tooling in your project. As far as updating the getting started guides, I opened an issue about adding this guide, but it hasn’t seen much progress yet.

Ultimately I think of this as my recommendation, but not necessarily something that would work as an official ‘PureScript’ stance. Still, I think it deserves a place somewhere in the official docs.

[JordanMartinez]

If you’re new to PureScript, you might find my repo helpful as well: http://www.github.com/jordanmartinez/purescript-jordans-reference

[tbenst]

This thread is super helpful, thank you all! Just thought I’d offer my current WIP for using Purescript with Nix: https://github.com/tbenst/purescript-nix-example

Unfortunately, I’m struggling to get spago bundle-app working (see default.nix):

purs bundle: No input files.
[error] Bundle failed.

Please let me know if you have suggestions!

Edit: that error was due to missing \ on line 28. Now I get a new error:

Couldn't find a CommonJS module for the specified main module: Example.Main
[error] Bundle failed.

I think this is because there is no Example in dist, but if I try to call spago without --no-install --no-build, it fails due to no internet connectivity in sandbox.

[tbenst]

Got it working! Here’s my nix derivation:

with import <nixpkgs> {};

let 
  spagoPkgs = import ./spago-packages.nix { inherit pkgs; };
in
mkYarnPackage rec {
  name = "purescript-nix-example";
  src = ./.;
  packageJSON = ./package.json;
  yarnLock = ./yarn.lock;

  nativeBuildInputs = [ purescript nodejs-12_x ];

  postBuild = ''
    ${purescript}/bin/purs compile "$src/**/*.purs" ${builtins.toString
      (builtins.map
        (x: ''"${x.outPath}/src/**/*.purs"'')
        (builtins.attrValues spagoPkgs.inputs))}
    cp -r $src/assets ./
    '';

  postFixup = ''
    ${spago}/bin/spago bundle-app --no-install \
      --no-build --main Example.Main --to dist/app.js
    mkdir -p $out/dist
    cp -r dist $out/
    ln -s $out/libexec/${name}/node_modules .
    ${nodejs-12_x}/bin/node node_modules/.bin/parcel \
      build assets/*.html --out-dir $out/dist/
  '';


  meta = with stdenv.lib; {
    description = "Example for building Purescript Halogen app with Nix.";
    homepage = "https://github.com/tbenst/purescript-nix-example";
    maintainers = with maintainers; [ tbenst ];
  };
}

Full code here.

[milesfrain]

On one hand, I like how unopinionated PS is, but on the other I don’t I think a lot of people don’t know how to get started, and yarn + spago + parcel is a great way to get going.

I agree that more opinionation would really improve the new user experience.

There’s currently no clear pathway to getting a web app running from the purescript.org landing page, even for users who read through both the quick start guide and the documentation page.

Something like create-react-app would be great. For now, it could just be a template clone command.

This would favor a particular toolchain and framework, but I don’t think that’s worse than the existing alternative of no direction. The unfairness could be partially remedied with a link to a “more frameworks” page.

Having official templates would also help focus everyone’s maintenance efforts and be a consistent springboard for tutorials.

For example, it would be nice if we could arrive at best practices from each of these 7 reasonable Halogen templates and track one of them under the purescript-contrib org.

purescript-halogen/purescript-halogen-template
citizennet/purescript-halogen-template
milesfrain/purescript-halogen-template/tree/tooling
cah6/purescript-halogen-template
charlescrain/create-react-app-halogen
tbenst/purescript-nix-example
JordanMartinez/learn-halogen/blob/latestRelease/src/05-ComponentTemplate-A.purs

Edit: Found some additional discourse discussion on create-react-app:

Incremental builds are slow

Another option might be a tool similar to create-react-app that allows people to easily create a new project with a fast build tool-chain already set up.

Differentiate PureScript "Groups" in Documentation?

It may turn out that the big problems that prevent folks from succeeding with PureScript for building single-page applications require solutions other than documentation, […] like create-react-app and so on.

Also, here are details on how create-react-app manages templates.

We can also look to create-elm-app for inspiration, which is an excellent new user experience.

Maybe we could someday reach the state where we’re just telling new users to run one of the following:

spago init --template halogen
spago init --template react-basic-hooks
spago init --template cli
... etc.

[f-f]

@milesfrain great points!
I opened this issue in Spago to track the addition of the --template flag as you mentioned in your post. I’ve been holding off on tracking this because I was not sure if it was a widespread need (vs just my feeling), but it looks like it would improve UX so I’d be happy to see this happening

[JamieBallingall]

Does it make sense to include a link to psa? Error and warning message quality is particularly important to new users.

[thomashoneyman]

Yes, I think it makes sense to link to psa – and as a note, Spago uses psa by default under the hood if it’s installed.

[tobia]

Since this thread is about opinionated recommendations, which editor / IDE would you recommend for PureScript development?

I’m a long time Sublime Text user, but I have found the ST plugin quite lacking. There is no auto-import, the import auto-complete is close to useless, the error reporting hover window comes out once every full moon and sometimes it gets stuck completely and I have to pkill -f purs.ide.server. I might as well keep it only for the syntax highlighting and just use some other aiding tool, such as the aforementioned pscid.

I’m conversant with Python, so I might pick up the ST plugin in the future and work on it, but for now I’m still learning PureScript, so I’d like to at least know what the state of the art is.

As of 2020, which IDE has the best integration, meaning the best auto-complete, auto-import, error reporting, type information, pop-up documentation, jump to definition, and such features?

[milesfrain]

I’ve had good experiences with vscode (using PS and purty plugins). All of these features work:

• auto-complete
• auto-import
• error reporting
• type information
• pop-up documentation
• jump to definition
• format-on-save

The only annoyances are:

• Need to Restart/Reconnect the IDE server after adding new functions in one file that are used in another file.
• None of the vim plugns in vscode are feature-complete. Workaround is to just briefly open a separate vim instance for more involved edits.

Has anyone used vim successfully for PS with the above feature set?

[thomashoneyman]

I mostly see VSCode or Emacs users. I use VSCode myself and it works smoothly.

As far as Vim goes I use a pretty limited feature set so I haven’t run into trouble.

[vanceism7]

I had this issue when I was using emacs as well. Have you tried enabling the option psc-ide-editor-mode (which may be named some what differently in vscode). I believe that fixed the issue of needing to restart the server for me

[milesfrain]

Have you tried enabling the option psc-ide-editor-mode

I’ll give that a shot. Currently disabled by default for me. Wondering why that is.

[ppq]

Using VScode and liking it! Make sure you install the plugin and launch the project from its folder

[tobia]

I switched to VSCode and it’s really good. Thank you!

[razcore-rad]

I’m using coc.nvim with purescript-language-server and I’m really pleased with it. Has all of the listed features and if I need to rebuild the project after installing a new dependency for example, I then just issues :CocRestart to refresh, but I think in theory it should pick up the new dependencies automatically.

[FranklinYu]

Hi, is this plugin the purty plugin you mentioned?

[milesfrain]

That’s the one. I’ll add the link to that post.

[bjornkihlberg]

If I am to do an FFI I like to include a jsconfig.json to get half decent type safety in JavaScript with JSDocs:

{
    "compilerOptions": {
        "checkJs": true,
        "strict": true,
        "target": "ES2017",
        "noImplicitAny": true,
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "moduleResolution": "node",
        "lib": ["es2020"]
    }
}