From fd91f9bf540d0cf4457106752d86b3b5481dc9a1 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferrai Date: Tue, 22 Jan 2019 11:06:42 +0200 Subject: [PATCH] Link examples of spago + parcel in the README (#83) --- README.md | 49 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 10fedd535..adb78ee93 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,9 @@ PureScript package manager and build tool powered by [Dhall][dhall] and - [`psc-package-local-setup`](#psc-package-local-setup) - [`psc-package-insdhall`](#psc-package-insdhall) - [FAQ](#faq) + - [Hey wait we have a perfectly functional `pulp` right?](#hey-wait-we-have-a-perfectly-functional-pulp-right) + - [So if I use `spago make-module` this thing will compile all my js deps in the file?](#so-if-i-use-spago-make-module-this-thing-will-compile-all-my-js-deps-in-the-file) + - [So I added a new package to the `packages.dhall`, why is `spago` not installing it?](#so-i-added-a-new-package-to-the-packagesdhall-why-is-spago-not-installing-it) @@ -204,14 +207,14 @@ let additions = { facebook = mkPackage [ "console" - , "aff" - , "prelude" - , "foreign" - , "foreign-generic" - , "errors" - , "effect" + , "aff" + , "prelude" + , "foreign" + , "foreign-generic" + , "errors" + , "effect" ] - "https://github.com/Unisay/purescript-facebook.git" + "https://github.com/Unisay/purescript-facebook.git" "v0.3.0" } ``` @@ -243,7 +246,7 @@ $ spago build --path 'another_source/**/*.purs' E.g. if you wish to output your files in some other place than `output/`, you can run ```bash -spago build -- -o myOutput/ +$ spago build -- -o myOutput/ ``` Anyways, the above will create a whole lot of files, but you might want to get just a @@ -326,7 +329,7 @@ echo wrote packages.json to $TARGET ## FAQ -> Hey wait we have a perfectly functional `pulp` right? +#### Hey wait we have a perfectly functional `pulp` right? Yees, however: - `pulp` is a build tool, so you'll still have to use it with `bower` or `psc-package`. @@ -340,7 +343,7 @@ Yees, however: we're doing here: integrating all the workflow in a single tool, `spago`, instead of having to use `pulp`, `psc-package`, `purp`, etc. -> So if I use `spago make-module` this thing will compile all my js deps in the file? +#### So if I use `spago make-module` this thing will compile all my js deps in the file? No. We only take care of PureScript land. In particular, `make-module` will do the most we can do on the PureScript side of things (dead code elimination), but will @@ -348,7 +351,29 @@ leave the `require`s still in. To fill them in you should use the proper js tool of the day, at the time of writing [ParcelJS][parcel] looks like a good option. -> So I added a new package to the `packages.dhall`, why is `spago` not installing it? +If you wish to see an example of a project building with `spago` + `parcel`, a simple +starting point is the [TodoMVC app with `react-basic`][todomvc]. +You can see in its `package.json` that a "production build" is just +`spago build && parcel build index.html`. +If you open its `index.js` you'll see that it does a `require('./output/Todo.App')`: +the files in `output` are generated by `spago build`, and then the `parcel` build resolves +all the `require`s and bundles all these js files in. + +Though this is not the only way to include the built js - for a slimmer build or for importing +some PureScript component in another js build we might want to use the output of `make-module`. + +For an example of this in a "production setting" you can take a look at [affresco][affresco]. +It is a PureScript monorepo of React-based components and apps. +The gist of it is that the PureScript apps in the repo are built with `spago build` +(look in the `package.json` for it), but all the React components can be imported from +JS apps as well, given that proper modules are built out of the PS sources. +This is where `spago make-module` is used: the `build-purs.rb` builds a bundle out of every +single React component in each component's folder - e.g. let's say we `make-module` from +the `ksf-login` component and output it in the `index.js` of the component's folder; we can +then `yarn install` the single component (note it contains a `package.json`), and require it +as a separate npm package with `require('@affresco/ksf-login')`. + +#### So I added a new package to the `packages.dhall`, why is `spago` not installing it? Adding a package to the package-set just includes it in the set of possible packages you can depend on. However if you wish `spago` to install it you should then add it to @@ -368,3 +393,5 @@ the `dependencies` list in your `spago.dhall`. [spago-npm]: https://www.npmjs.com/package/purescript-spago [spago-latest-release]: https://github.com/spacchetti/spago/releases/latest [spago-issues]: https://github.com/spacchetti/spacchetti-cli/issues +[affresco]: https://github.com/KSF-Media/affresco/tree/4b430b48059701a544dfb65b2ade07ef9f36328a +[todomvc]: https://github.com/f-f/purescript-react-basic-todomvc