diff --git a/.gitignore b/.gitignore index a87368d..615d4d3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,13 @@ -.* -!.gitignore -!.travis.yml -!.purs-repl - -.spago -bower_components -node_modules -output - -*.lock -package-lock.json - -dist/app.js +/bower_components/ +/node_modules/ +/.pulp-cache/ +/output/ +/generated-docs/ +/.psc-package/ +/.psc* +/.purs* +/.psa* +/.spago +/.cache/ +/dist/ +/prod/* diff --git a/README.md b/README.md index 964340e..c86d1f6 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,32 @@ # Halogen Template -This is a template for starting a fresh project with the [Halogen](https://github.com/slamdata/purescript-halogen) library for writing declarative, type-safe user interfaces. +### Quick Start +```sh +git clone https://github.com/purescript-halogen/purescript-halogen-template.git halogen-project +cd halogen-project +npm install +npm run build +npm run serve +``` + +### Introduction + +This is a template for starting a fresh project with the [Halogen](https://github.com/purescript-halogen/purescript-halogen) library for writing declarative, type-safe user interfaces. You can learn more about Halogen with these resources: - The [Halogen documentation](https://github.com/purescript-halogen/purescript-halogen/tree/master/docs), which includes a quick start guide and a concepts reference. - The [Learn Halogen](https://github.com/jordanmartinez/learn-halogen) learning repository. -- The [Real World Halogen](https://github.com/thomashoneyman/purescript-halogen-realworld) application and guide. +- The [Real World Halogen](https://github.com/thomashoneyman/purescript-halogen-realworld) application and guide. Note that the published article is written for the older halogen v4, but the code and comments cover the current halogen v5. - The [API documentation](https://pursuit.purescript.org/packages/purescript-halogen) on Pursuit You can chat with other Halogen users on the [PureScript Discourse](https://discourse.purescript.org), or join the [Functional Programming Slack](https://functionalprogramming.slack.com) ([invite link](https://fpchat-invite.herokuapp.com/)) in the `#purescript` and `#purescript-beginners` channels. -## Getting started +If you notice any problems with the below setup instructions, or have suggestions on how to make the new-user experience any smoother, please create an issue or pull-request. + +Compatible with PureScript compiler 13.x + +### Initial Setup **Prerequisites:** This template assumes you already have Git and Node.js installed with `npm` somewhere on your path. @@ -22,15 +37,19 @@ git clone https://github.com/purescript-halogen/purescript-halogen-template.git cd halogen-project ``` -Then, install the PureScript compiler, the [Spago](https://github.com/purescript/spago) package manager and build tool, and [Webpack](https://github.com/webpack/webpack) bundler locally: +Then, install the PureScript compiler, the [Spago](https://github.com/purescript/spago) package manager and build tool, and the [Parcel](https://github.com/parcel-bundler/parcel) bundler. You may either install PureScript tooling _globally_, to reduce duplicated `node_modules` across projects, or _locally_, so that each project uses specific versions of the tools. -```shell -npm install +To install the toolchain globally: +```sh +npm install -g purescript spago parcel ``` -This will automatically trigger Spago to install the PureScript library dependencies for this project. +To install the toolchain locally (reads `devDependencies` from `package.json`): +```sh +npm install +``` -## Building +### Building You can now build the PureScript source code with: @@ -39,19 +58,34 @@ You can now build the PureScript source code with: npm run build ``` -You can produce a bundled JS file you can run in the browser with: +### Launching the App + +You can launch your app in the browser with: ```sh -# An alias for `spago bundle-app --to dist/app.js` -npm run bundle +# An alias for `parcel dev/index.html --out-dir dev-dist --open` +npm run serve ``` -This deposits a bundled JS file named `app.js` in the `dist` directory. You can view your running Halogen app by opening the `dist/index.html` file. +### Development Cycle + +If you're using an [editor](https://github.com/purescript/documentation/blob/master/ecosystem/Editor-and-tool-support.md#editors) that supports [`purs ide`](https://github.com/purescript/purescript/tree/master/psc-ide) or are running [`pscid`](https://github.com/kRITZCREEK/pscid), you simply need to keep the previous `npm run serve` command running in a terminal. Any save to a file will trigger an incremental recompilation, rebundle, and web page refresh, so you can immediately see your changes. + +If your workflow does not support automatic recompilation, then you will need to manually re-run `npm run build`. Even with automatic recompilation, a manual rebuild is occasionally required, such as when you add, remove, or modify module names, or notice any other unexpected behavior. + +### Production + +When you are ready to create a minified bundle for deployment, run the following command: +```sh +npm run build-prod +``` -Alternatively, if you use an editor that supports `purs ide` or if you are running [`pscid`](https://github.com/kRITZCREEK/pscid), then you can get near-instant builds of the app while you work: +Parcel output appears in the `./dist/` directory. +You can test the production output locally with a tool like [`http-server`](https://github.com/http-party/http-server#installation). It seems that `parcel` should also be able to accomplish this, but it unfortunately will only serve development builds locally. ```sh -npm run bundle:watch +npm install -g http-server +http-server dist -o ``` -:warning: `purs ide` only rebuilds one module at a time, so sometimes the bundle will end up in an inconsistent state, resulting in runtime errors. This occurs when a change is made in one module that breaks other modules that depend on it. The solution is to run a full build when a change like this is made, as the compiler will force you to resolve those errors. +If everything looks good, you can then upload the contents of `dist` to your preferred static hosting service. diff --git a/dev/index.html b/dev/index.html new file mode 100644 index 0000000..e90d524 --- /dev/null +++ b/dev/index.html @@ -0,0 +1,10 @@ + + + + + Halogen5 Template + + + + + diff --git a/dev/index.js b/dev/index.js new file mode 100644 index 0000000..db8b552 --- /dev/null +++ b/dev/index.js @@ -0,0 +1 @@ +require("../output/Main/index.js").main(); diff --git a/dist/index.html b/dist/index.html deleted file mode 100644 index fd93d38..0000000 --- a/dist/index.html +++ /dev/null @@ -1,10 +0,0 @@ - - - - - My Halogen App - - - - - diff --git a/entry.js b/entry.js deleted file mode 100644 index 4ceadbd..0000000 --- a/entry.js +++ /dev/null @@ -1 +0,0 @@ -require("./output/Main").main(); diff --git a/package.json b/package.json index a8e7a75..aa66dfc 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,13 @@ { "private": true, - "scripts": { - "test": "spago test", - "build": "spago build", - "bundle": "spago bundle-app --to dist/app.js", - "bundle:watch": "webpack --mode=development --entry ./entry.js --output-path ./dist --output-filename app.js --progress --watch" - }, "devDependencies": { + "parcel": "^1.12.4", "purescript": "^0.13.8", - "purescript-psa": "^0.7.3", - "spago": "^0.15.2", - "webpack": "^4.43.0", - "webpack-cli": "^3.3.11" + "spago": "^0.15.3" + }, + "scripts": { + "build": "spago build", + "serve": "parcel dev/index.html --open", + "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" } -} +} \ No newline at end of file diff --git a/packages.dhall b/packages.dhall index 2dc7c50..e01462d 100644 --- a/packages.dhall +++ b/packages.dhall @@ -118,7 +118,7 @@ let additions = -} let upstream = - https://github.com/purescript/package-sets/releases/download/psc-0.13.6-20200507/packages.dhall sha256:9c1e8951e721b79de1de551f31ecb5a339e82bbd43300eb5ccfb1bf8cf7bbd62 + https://github.com/purescript/package-sets/releases/download/psc-0.13.8-20200615/packages.dhall sha256:5d0cfad9408c84db0a3fdcea2d708f9ed8f64297e164dc57a7cf6328706df93a let overrides = {=} diff --git a/spago.dhall b/spago.dhall index a8753f7..b007060 100644 --- a/spago.dhall +++ b/spago.dhall @@ -1,5 +1,5 @@ { name = "halogen-project" -, dependencies = [ "halogen", "psci-support" ] +, dependencies = [ "console", "effect", "halogen", "psci-support" ] , packages = ./packages.dhall , sources = [ "src/**/*.purs", "test/**/*.purs" ] }