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