README.md

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