]>
Commit | Line | Data |
---|---|---|
a42f24b8 | 1 | # purs-loader |
2 | ||
08b34471 | 3 | > [PureScript](http://www.purescript.org) loader for [webpack](http://webpack.github.io) |
a42f24b8 | 4 | |
7de41f10 AM |
5 | - Supports hot-reloading and rebuilding of single source files |
6 | - Dead code elimination using the `bundle` option | |
7 | - Colorized build output using `purescript-psa` and the `psc: "psa"` option | |
8 | ||
a42f24b8 | 9 | ## Install |
10 | ||
63d6a244 | 11 | Install with [npm](https://npmjs.org/package/purs-loader). |
12 | ||
a42f24b8 | 13 | ``` |
1c12889c | 14 | // For PureScript 0.11 and newer |
a9a26a84 | 15 | npm install purs-loader --save-dev |
2b2207bd | 16 | |
1c12889c | 17 | // For PureScript 0.9 and 0.10 |
18 | npm install purs-loader@purescript-0.9 --save-dev | |
19 | ||
495b765e | 20 | // For PureScript 0.8 |
689268da | 21 | npm install purs-loader@purescript-0.8 --save-dev |
a42f24b8 | 22 | ``` |
23 | ||
a42f24b8 | 24 | ## Example |
25 | ||
7de41f10 AM |
26 | ```javascript |
27 | const webpackConfig = { | |
28 | // ... | |
29 | loaders: [ | |
30 | // ... | |
31 | { | |
32 | test: /\.purs$/, | |
33 | loader: 'purs-loader', | |
34 | exclude: /node_modules/, | |
35 | query: { | |
36 | psc: 'psa', | |
2b2207bd | 37 | src: ['bower_components/purescript-*/src/**/*.purs', 'src/**/*.purs'] |
7de41f10 AM |
38 | } |
39 | } | |
40 | // ... | |
41 | ] | |
42 | // ... | |
43 | } | |
44 | ``` | |
45 | ||
44eb153b | 46 | Refer to the [purescript-webpack-example](https://github.com/ethul/purescript-webpack-example) for a more detailed example. |
47 | ||
5163b5a2 AM |
48 | ### Options |
49 | ||
7de41f10 AM |
50 | Default options: |
51 | ||
52 | ```javascript | |
86e2b3d4 | 53 | const loaderConfig = { |
f5643707 | 54 | psc: null, // purs compile |
7de41f10 | 55 | pscArgs: {}, |
f5643707 | 56 | pscBundle: null, // purs bundle |
7de41f10 | 57 | pscBundleArgs: {}, |
5163b5a2 | 58 | pscIde: false, // instant rebuilds using psc-ide-server (experimental) |
71a96808 | 59 | pscIdeClient: null, // purs ide client |
60 | pscIdeClientArgs: {}, // for example, to use different port {port: 4088} | |
61 | pscIdeServer: null, // purs ide server | |
cd124999 | 62 | pscIdeServerArgs: {}, // for example, to change the port {port: 4088} |
63 | pscIdeRebuildArgs: {} // for example, for sourcemaps {codegen: ['js', 'sourcemaps']} | |
7de41f10 | 64 | pscIdeColors: false, // defaults to true if psc === 'psa' |
bef7f4e2 DH |
65 | pscPackage: false, // include dependencies from psc-package |
66 | spago: false, // include dependencies from spago | |
7de41f10 AM |
67 | bundleOutput: 'output/bundle.js', |
68 | bundleNamespace: 'PS', | |
69 | bundle: false, | |
70 | warnings: true, | |
cbb75795 | 71 | watch: false, // indicates if webpack is in watch mode |
7de41f10 AM |
72 | output: 'output', |
73 | src: [ | |
74 | path.join('src', '**', '*.purs'), | |
495b765e | 75 | // if pscPackage = true |
76 | // source paths reported by `psc-package sources` | |
bef7f4e2 DH |
77 | // if spago = true |
78 | // source paths reported by `spago sources` | |
79 | // if pscPackage = false and spago = false | |
80 | path.join('bower_components', 'purescript-*', 'src', '**', '*.purs') | |
2b2207bd | 81 | ] |
7de41f10 AM |
82 | } |
83 | ``` | |
5163b5a2 | 84 | |
495b765e | 85 | ### `psc-ide` support (experimental) |
5163b5a2 AM |
86 | |
87 | Experimental support for instant rebuilds using `psc-ide-server` can be enabled | |
88 | via the `pscIde: true` option. | |
4343e0eb MK |
89 | You can use an already running `psc-ide-server` instance by specifying the port in `pscIdeArgs`, |
90 | if there is no server running this loader will start one for you. | |
91 | ||
03f52cb3 | 92 | ### `psc-package` support (experimental) |
93 | ||
94 | Set `pscPackage` query parameter to `true` to enable `psc-package` support. The `psc-package`-supplied source paths | |
95 | will be appended to `src` parameter. | |
96 | ||
bef7f4e2 DH |
97 | ### `spago` support (experimental) |
98 | ||
99 | Set `spago` query parameter to `true` to enable `spago` support. The `spago`-supplied source paths | |
100 | will be appended to `src` parameter. | |
101 | ||
03f52cb3 | 102 | ### Troubleshooting |
4343e0eb | 103 | |
03f52cb3 | 104 | #### Slower webpack startup after enabling psc-ide support? |
4343e0eb MK |
105 | |
106 | By default, the psc-ide-server will be passed the globs from query.src, this is | |
107 | helpful for other tools using psc-ide-server (for example IDE plugins), however | |
108 | it might result in a slower initial webpack startup time (rebuilds are not | |
109 | affected). To override the default behaviour, add: | |
110 | `pscIdeServerArgs: { "_": ['your/*globs/here'] }` to the loader config | |
111 | ||
03f52cb3 | 112 | #### Errors not being displayed in watch mode? |
4343e0eb | 113 | |
03f52cb3 | 114 | When the `watch` option is set to `true`, psc errors are appended to |
115 | webpack's compilation instance errors array and not passed back as an | |
116 | error to the loader's callback. This may result in the error not being | |
117 | reported by webpack. To display errors, the following plugin may be added | |
118 | to the webpack config. | |
119 | ||
120 | ```javascript | |
121 | const webpackConfig = { | |
122 | // ... | |
123 | plugins: [ | |
124 | function(){ | |
125 | this.plugin('done', function(stats){ | |
126 | process.stderr.write(stats.toString('errors-only')); | |
127 | }); | |
128 | } | |
129 | ] | |
130 | // ... | |
131 | } | |
132 | ``` | |
ab944285 | 133 | |
134 | #### Error `spawn ENOENT` | |
135 | ||
136 | This is caused when the loader tries to spawn a binary that does not exists | |
137 | (`file or directory not found`). If you call webpack like `webpack` or | |
be05a055 | 138 | `webpack --watch`, then ensure that all required binaries that the |
ab944285 | 139 | loader depends on are available in your `$PATH`. |
140 | ||
be05a055 | 141 | If you run webpack through an npm script (e.g., npm run or npm start) on NixOS, |
142 | then it will first attempt to find binaries in `node_packages/.bin`. | |
143 | If you have the compiler installed through `npm` and it finds it there, this will | |
144 | cause `ENOENT`on Nix, because [the binary needs to be patched first, but npm will | |
145 | install the binary that is linked with /lib64/ld-linux-x86-64.so.2 - a file that | |
146 | will not exist at that path in NixOS](https://github.com/ethul/purescript-webpack-example/issues/5#issuecomment-282492131). | |
ab944285 | 147 | The solution is to simply use the compiler from `haskellPackages.purescript` and |
148 | make sure that it's available in `$PATH`. For more information about how to make | |
149 | it work on Nix, see [Purescript Webpack Example](https://github.com/ethul/purescript-webpack-example#using-globally-installed-binaries) |