purescript-halogen / purescript-halogen-template

Template project for getting started with Halogen

Halogen

Halogen is a type-safe library for building user interfaces in PureScript.

• Declarative Write simple views for each state in your application, and Halogen will efficiently and intelligently update the right components and re-render your user interface.
• Component Architecture Write encapsulated components which manage their own state, and compose them together to build complex user interfaces. Or, use a single component to implement an Elm-like architecture.
• Entirely PureScript Halogen and its virtual DOM implementation are written in PureScript. Halogen's performance and bundle sizes are roughly equivalent to popular JavaScript UI libraries like React and Angular.

Read the documentation to learn how to use Halogen in your own projects.

Installation

Install Halogen with Spago:

spago install halogen

Or create a new Halogen app from a template.

Documentation

You can find the Halogen documentation on the documentation site or in the docs folder. Documentation is divided into several categories:

• Halogen Guide
• Concepts Reference (Coming soon)
• API Reference on Pursuit
• Major Version Changelog

We also recommend these community resources for learning how to use Halogen in your applications:

• Real World Halogen by Thomas Honeyman

There are several ways to get help if you get stuck using Halogen:

• Open an issue if you have encountered a bug or problem.
• Start a thread on the PureScript Discourse or browse the #halogen tag if you have general questions about Halogen.
• Join the PureScript Discord to chat about Halogen with other PureScript users.

Examples

This repository contains several self-contained examples, ranging from a basic button to controlling external components.

You may also want to review the Real World Halogen example application, which demonstrates routing, state management, authentication, making requests, and other real world examples with commented explanations.

Contributing

The main purpose of this repository is to continue evolving Halogen, making it faster and easier to use. Halogen is developed in the open on GitHub and we're grateful for community-contributed bugfixes and improvements.

You can take part in improving Halogen by opening or participating in issues, opening pull requests to add new features, documentation, or tests, and by helping other Halogen users on Discord and Discourse.

License & Credits

Halogen is licensed under the Apache License 2.0. The Halogen logo was designed by Matthew Park.

purescript-halogen-template's Issues

Redundant rm dist in build-prod package.json

Hi I was picking stuffs from this repo for my own halogen project when I noticed there is a redundant rm -rf dist as below:

purescript-halogen-template/package.json

Line 12 in 9cc04ea

"build-prod": "mkdir -p prod && cp dev/index.html prod/ && rm -rf dist && spago bundle-app --to prod/index.js && parcel build prod/index.html"

Is this a mistake? Or there is something underlying which I am not aware?

or should it be this:

 "build-prod": "rm -rf prod && mkdir -p prod && cp dev/index.html prod/ && spago bundle-app --to prod/index.js && parcel build prod/index.html" 

Thank you.

Unable to build

steps to reproduce:

1. clone repo
2. bower i
3. npm run build

Start work on Halogen 5 version

It might be good to start working on a Halogen 5 version while it's still pre-release.

Invalid Version: undefined

Following the instructions in the README leads to the error Invalid Version: undefined when running either npm run serve or npm run build-prod.

This appears to be a result of a change to Babel causing problems with Parcel.

A temporary fix is to pin the Parcel version to 1.12.3 (rather than ^1.12.4) until the Parcel folks sort this out.

`npm install` fails on NixOS (Error: [email protected] postinstall)

The error message unfortunately is not totally clear on the cause of the crash, but I can't seem to use this template on NixOS following the README instructions.

1782 verbose stack Error: [email protected] postinstall: `install-purescript --purs-ver=0.14.0`
1782 verbose stack Exit status 1
1782 verbose stack     at EventEmitter.<anonymous> (/nix/store/6mbng3dq3q28r5mi4p58dkig9j2v348h-nodejs-12.21.0/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:332:16)
1782 verbose stack     at EventEmitter.emit (events.js:314:20)
1782 verbose stack     at ChildProcess.<anonymous> (/nix/store/6mbng3dq3q28r5mi4p58dkig9j2v348h-nodejs-12.21.0/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
1782 verbose stack     at ChildProcess.emit (events.js:314:20)
1782 verbose stack     at maybeClose (internal/child_process.js:1022:16)
1782 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5)
1783 verbose pkgid [email protected]
1784 verbose cwd /home/srid/code/purescript-halogen-template
1785 verbose Linux 5.11.2
1786 verbose argv "/nix/store/6mbng3dq3q28r5mi4p58dkig9j2v348h-nodejs-12.21.0/bin/node" "/home/srid/.nix-profile/bin/npm" "install"
1787 verbose node v12.21.0
1788 verbose npm  v6.14.11
1789 error code ELIFECYCLE
1790 error errno 1
1791 error [email protected] postinstall: `install-purescript --purs-ver=0.14.0`
1791 error Exit status 1
1792 error Failed at the [email protected] postinstall script.
1792 error This is probably not a problem with npm. There is likely additional logging output above.
1793 verbose exit [ 1, true ]

Updating the template for PureScript 0.10.1 breaking changes

Hi,
I just installed purescript 0.10.1 and that may have introduced breaking changes as specified at Release.

Hence, I can't build the template.

npm run build

..
Error 1 of 3:

 in module Control.Monad.Aff.Console
 at /Users/rajivabraham/Google Drive/dev/purescript/purescript-kaytalk/bower_components/purescript-aff/src/Control/Monad/Aff/Console.purs line 36, column 1 - line 36, column 34

   No type class instance was found for

     Control.Monad.Eff.Class.MonadEff ( console :: CONSOLE
                                      | t0
                                      )
                                      (Aff
                                         ( console :: CONSOLE
                                         | eff1
                                         )
                                      )

   The instance head contains unknown type variables. Consider adding a type annotation.

 while checking that expression (compose liftEff) warnShow
   has type forall a eff.
              (Show a) => a
                          -> Aff
                               ( console :: CONSOLE
                               | eff
                               )
                               Unit
 while applying a function compose
   of type forall b c d a. (Semigroupoid a) => a c d -> a b c -> a b d
   to argument liftEff
 in value declaration warnShow

 where eff1 is a rigid type variable
         bound at line 36, column 1 - line 36, column 34
       t0 is an unknown type

 See https://github.com/purescript/purescript/wiki/Error-Code-NoInstanceFound for more information,
 or to contribute content related to this error.

Error 2 of 3:

 in module Halogen.HTML.Renderer.VirtualDOM
 at /Users/rajivabraham/Google Drive/dev/purescript/purescript-kaytalk/bower_components/purescript-halogen/src/Halogen/HTML/Renderer/VirtualDOM.purs line 59, column 1 - line 60, column 43

   No type class instance was found for

     Control.Monad.Eff.Class.MonadEff ( dom :: DOM
                                      | t0
                                      )
                                      (Aff
                                         ( avar :: AVAR
                                         , err :: EXCEPTION
                                         , dom :: DOM
                                         | eff1
                                         )
                                      )

   The instance head contains unknown type variables. Consider adding a type annotation.

 while checking that expression \$2 ->
                                  \$3 ->
                                    case $2 $3 of
                                      _ (Prop e) -> ...
                                      _ (Attr ns name value) -> ...
                                      dr (Handler e) -> ...
                                      dr (Ref f) -> ...
                                      _ _ -> ...
   has type forall f eff.
              (forall i.
                 f i
                 -> Aff
                      ( avar :: AVAR
                      , err :: EXCEPTION
                      , dom :: DOM
                      | eff
                      )
                      i
              )
              -> Prop (f Unit) -> Props
 while applying a function runExistsR
   of type forall f r. (forall a. f a -> r) -> ExistsR f -> r
   to argument \$1 ->
                 case $1 of
                   (HandlerF name k) -> (...) (...)
 in value declaration renderProp

 where eff1 is a rigid type variable
         bound at line 59, column 1 - line 60, column 43
       t0 is an unknown type

 See https://github.com/purescript/purescript/wiki/Error-Code-NoInstanceFound for more information,
 or to contribute content related to this error.

Error 3 of 3:

 in module Halogen.Util
 at /Users/rajivabraham/Google Drive/dev/purescript/purescript-kaytalk/bower_components/purescript-halogen/src/Halogen/Util.purs line 50, column 1 - line 56, column 76

   No type class instance was found for

     Control.Monad.Eff.Class.MonadEff ( dom :: DOM
                                      | t0
                                      )
                                      (Aff
                                         ( dom :: DOM
                                         | eff1
                                         )
                                      )

   The instance head contains unknown type variables. Consider adding a type annotation.

 while checking that expression \query ->
                                  (bind ((...) (...))) (\$0 ->
                                                          case $0 of
                                                            ...
                                                       )
   has type forall eff.
              String
              -> Aff
                   ( dom :: DOM
                   | eff
                   )
                   (Maybe HTMLElement)
 while applying a function bind
   of type forall a b m. (Bind m) => m a -> (a -> m b) -> m b
   to argument (apply liftEff) ((map toMaybe) ((bindFlipped (...)) window))
 in value declaration selectElement

 where eff1 is a rigid type variable
         bound at line 50, column 1 - line 56, column 76
       t0 is an unknown type

 See https://github.com/purescript/purescript/wiki/Error-Code-NoInstanceFound for more information,
 or to contribute content related to this error.

Full Error output at: http://pastebin.com/YG8cKFpb

xmlns:foo?

https://github.com/slamdata/purescript-halogen-template/blob/cebbb9fd48d438b5223c07630cc6104ec0e5d4cd/dist/index.html#L2

creates a namespace called 'foo'. Is that required? Given it the connotations of 'foo' as a placeholder name it creates confusion around the role of SVG in Halogen apps.

I believe it could simply be removed, since SVG would be within the HTML document and therefore unable to have its own namespace anyway.

Having the main component be a button is a bit misleading

While this repo isn't necessarily meant as a direct learning resource, it's still going to be the first thing some people encounter when trying to get hands-on with Halogen.

Having the component in here as App/Button.purs is not very helpful with that, as in normal situations it would be something like App/Component.purs, which then might well have a button inside it, or a child button component or whatever. Basically, I feel like straight out of the box it's set up wrong for what someone would actually want as a starting point for a project.

Can't build cloned repo

I did the following about five minutes or so ago.

• sudo npm install purescript pulp bower -g
• git clone <...> halogen-test
• npm run build

I get an invalid option --censor-lib error.

Output of npm run build:

mrkgnao@underflow ~/c/p/halogen-test> npm run build

> purescript-halogen@ build /home/mrkgnao/code/ps/halogen-test
> pulp build --censor-lib --strict

* Building project in /home/mrkgnao/code/ps/halogen-test
Invalid option `--censor-lib'

Usage: psc [FILE] [-o|--output ARG] [--no-tco] [--no-magic-do] [--no-opts]
           [-v|--verbose-errors] [-c|--comments] [--source-maps]
           [-p|--no-prefix] [--json-errors]
* ERROR: Subcommand terminated with exit code 1

npm ERR! Linux 4.6.2-1-ARCH
npm ERR! argv "/usr/bin/node" "/usr/bin/npm" "run" "build"
npm ERR! node v6.2.2
npm ERR! npm  v3.9.6
npm ERR! code ELIFECYCLE
npm ERR! purescript-halogen@ build: `pulp build --censor-lib --strict`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the purescript-halogen@ build script 'pulp build --censor-lib --strict'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the purescript-halogen package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     pulp build --censor-lib --strict
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs purescript-halogen
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls purescript-halogen
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     /home/mrkgnao/code/ps/halogen-test/npm-debug.log

Here is the output of pulp build:

mrkgnao@underflow ~/c/p/halogen-test> pulp build
* Building project in /home/mrkgnao/code/ps/halogen-test
psc: No files found using pattern: bower_components/purescript-*/src/**/*.purs
Error found:
at /home/mrkgnao/code/ps/halogen-test/src/Halogen/Component.purs line 464, column 28 - line 464, column 28

  Unable to parse module:
  unexpected =
  expecting :, , or }


See https://github.com/purescript/purescript/wiki/Error-Code-ErrorParsingModule for more information,
or to contribute content related to this error.


* ERROR: Subcommand terminated with exit code 1
mrkgnao@underflow ~/c/p/halogen-test> npm run build

> purescript-halogen@ build /home/mrkgnao/code/ps/halogen-test
> pulp build --censor-lib --strict

* Building project in /home/mrkgnao/code/ps/halogen-test
Invalid option `--censor-lib'

Usage: psc [FILE] [-o|--output ARG] [--no-tco] [--no-magic-do] [--no-opts]
           [-v|--verbose-errors] [-c|--comments] [--source-maps]
           [-p|--no-prefix] [--json-errors]
* ERROR: Subcommand terminated with exit code 1

If it helps, I'm on a fresh (yesterday) Arch install, and I'm having some problems with Unicode for some reason that make yaourt say things like n° instead of "nº" or whatever it is supposed to say. Fixed, doesn't help.

Invitation link broken

Slack invitation is broken
(I think I saw it being used in another repository as well)

Update to latest PureScript and Halogen versions

package.json and bower.json would need to be updated.

Auto refresh breaks when listening on all interfaces

Hello!

Trying a bit of PureScript and Halogen today :)

Launching this command, I can access the web server fine from another device on my local network.

npm run serve -- --host=0.0.0.0

However, auto-refreshing the page won't work because the websocket tries to connect to the wrong address.

I'm not sure who owns that code but maybe there's something you could do about it?

runtime-c0fb628751bc271e.js:94         
WebSocket connection to 'ws://0.0.0.0:1234/' failed: Error in connection establishment: net::ERR_ADDRESS_INVALID

Hacky workaround to grab my local IP:

npm run serve -- --host=$(hostname -I | awk '{print $1}')

But that breaks localhost unfortunately :(

A minor nuisance

Add -O to browserify build

Without it even this tiny app kicks in at 800Kb. Not good for public performances ;)

Converge on template best practices

Now that this template is updated to V5, I'd like to deprecate this other template to consolidate maintenance efforts:
https://github.com/purescript-templates/halogen/

What workflow should we suggest to new users? Parcel (featured in the other template) seems like a more beginner friendly option than webpack, and it includes automatic page refresh. With this template, a tool like live-server is required.