X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=README.md;h=d82893d591bb2233f1bfe0da6f084b9f8ec55f30;hb=7f0547d4e02d927e766de340152a2f75b659d889;hp=a459059db1f9bbcf41eec373bfbeea66a21859a2;hpb=63d6a244462d050e119bde54a7063bae8a17e987;p=github%2Ffretlink%2Fpurs-loader.git diff --git a/README.md b/README.md index a459059..d82893d 100644 --- a/README.md +++ b/README.md @@ -2,54 +2,137 @@ > [PureScript](http://www.purescript.org) loader for [webpack](http://webpack.github.io) +- Supports hot-reloading and rebuilding of single source files +- Dead code elimination using the `bundle` option +- Colorized build output using `purescript-psa` and the `psc: "psa"` option + ## Install Install with [npm](https://npmjs.org/package/purs-loader). -This loader works in conjunction with the [PureScript webpack plugin](https://npmjs.org/package/purescript-webpack-plugin). Ensure the plugin is installed and configured accordingly. - ``` +// For PureScript 0.11 and newer npm install purs-loader --save-dev + +// For PureScript 0.9 and 0.10 +npm install purs-loader@purescript-0.9 --save-dev + +// For PureScript 0.8 +npm install purs-loader@purescript-0.8 --save-dev ``` -## Options +## Example -###### `pscBundle` (String) +```javascript +const webpackConfig = { + // ... + loaders: [ + // ... + { + test: /\.purs$/, + loader: 'purs-loader', + exclude: /node_modules/, + query: { + psc: 'psa', + src: ['bower_components/purescript-*/src/**/*.purs', 'src/**/*.purs'] + } + } + // ... + ] + // ... +} +``` -Relative path to the bundled JavaScript file generated by the `PurescriptWebpackPlugin`. The default value is `output/bundle.js`. +Refer to the [purescript-webpack-example](https://github.com/ethul/purescript-webpack-example) for a more detailed example. + +### Options + +Default options: + +```javascript +const loaderConfig = { + psc: 'psc', + pscArgs: {}, + pscBundle: 'psc-bundle', + pscBundleArgs: {}, + pscIde: false, // instant rebuilds using psc-ide-server (experimental) + pscIdeArgs: {}, // for example, to use different psc-ide-server port: {port: 4088} + pscIdeServerArgs: {}, // for example, to change the port { port: 4088 } + pscIdeColors: false, // defaults to true if psc === 'psa' + pscPackage: false, + bundleOutput: 'output/bundle.js', + bundleNamespace: 'PS', + bundle: false, + warnings: true, + watch: false, // indicates if webpack is in watch mode + output: 'output', + src: [ + path.join('src', '**', '*.purs'), + // if pscPackage = false + path.join('bower_components', 'purescript-*', 'src', '**', '*.purs') + // if pscPackage = true + // source paths reported by `psc-package sources` + ] +} +``` -## Example +### `psc-ide` support (experimental) -```js -// webpack.config.js -'use strict'; +Experimental support for instant rebuilds using `psc-ide-server` can be enabled +via the `pscIde: true` option. +You can use an already running `psc-ide-server` instance by specifying the port in `pscIdeArgs`, +if there is no server running this loader will start one for you. -var PurescriptWebpackPlugin = require('purescript-webpack-plugin'); +### `psc-package` support (experimental) -var src = ['bower_components/purescript-*/src/**/*.purs', 'src/**/*.purs']; +Set `pscPackage` query parameter to `true` to enable `psc-package` support. The `psc-package`-supplied source paths +will be appended to `src` parameter. -var ffi = ['bower_components/purescript-*/src/**/*.js', 'src/**/*FFI.js']; +### Troubleshooting -var modulesDirectories = [ - 'node_modules', - 'bower_components' -]; +#### Slower webpack startup after enabling psc-ide support? -var config - = { entry: './src/entry' - , output: { path: __dirname - , pathinfo: true - , filename: 'bundle.js' - } - , module: { loaders: [ { test: /\.purs$/ - , loader: 'purs-loader' - } ] } - , resolve: { modulesDirectories: modulesDirectories } - , plugins: [ new PurescriptWebpackPlugin({src: src, ffi: ffi}) ] - } - ; +By default, the psc-ide-server will be passed the globs from query.src, this is +helpful for other tools using psc-ide-server (for example IDE plugins), however +it might result in a slower initial webpack startup time (rebuilds are not +affected). To override the default behaviour, add: +`pscIdeServerArgs: { "_": ['your/*globs/here'] }` to the loader config -module.exports = config; +#### Errors not being displayed in watch mode? + +When the `watch` option is set to `true`, psc errors are appended to +webpack's compilation instance errors array and not passed back as an +error to the loader's callback. This may result in the error not being +reported by webpack. To display errors, the following plugin may be added +to the webpack config. + +```javascript +const webpackConfig = { + // ... + plugins: [ + function(){ + this.plugin('done', function(stats){ + process.stderr.write(stats.toString('errors-only')); + }); + } + ] + // ... +} ``` -See the [example](https://github.com/ethul/purs-loader/tree/master/example) directory for a complete example. +#### Error `spawn ENOENT` + +This is caused when the loader tries to spawn a binary that does not exists +(`file or directory not found`). If you call webpack like `webpack` or +`webpack --watch`, then ensure that all required binaries that the +loader depends on are available in your `$PATH`. + +If you run webpack through an npm script (e.g., npm run or npm start) on NixOS, +then it will first attempt to find binaries in `node_packages/.bin`. +If you have the compiler installed through `npm` and it finds it there, this will +cause `ENOENT`on Nix, because [the binary needs to be patched first, but npm will +install the binary that is linked with /lib64/ld-linux-x86-64.so.2 - a file that +will not exist at that path in NixOS](https://github.com/ethul/purescript-webpack-example/issues/5#issuecomment-282492131). +The solution is to simply use the compiler from `haskellPackages.purescript` and +make sure that it's available in `$PATH`. For more information about how to make +it work on Nix, see [Purescript Webpack Example](https://github.com/ethul/purescript-webpack-example#using-globally-installed-binaries)