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.11 and newer
  15 npm install purs-loader --save-dev
  16
  17 // For PureScript 0.9 and 0.10
  18 npm install purs-loader@purescript-0.9 --save-dev
  19
  20 // For PureScript 0.8
  21 npm install purs-loader@purescript-0.8 --save-dev
  22 ```
  23
  24 ## Example
  25
  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',
  37         src: ['bower_components/purescript-*/src/**/*.purs', 'src/**/*.purs']
  38       }
  39     }
  40     // ...
  41   ]
  42   // ...
  43 }
  44 ```
  45
  46 Refer to the [purescript-webpack-example](https://github.com/ethul/purescript-webpack-example) for a more detailed example.
  47
  48 ### Options
  49
  50 Default options:
  51
  52 ```javascript
  53 const loaderConfig = {
  54   psc: null, // purs compile
  55   pscArgs: {},
  56   pscBundle: null, // purs bundle
  57   pscBundleArgs: {},
  58   pscIde: false, // instant rebuilds using psc-ide-server (experimental)
  59   pscIdeClient: null, // purs ide client
  60   pscIdeClientArgs: {}, // for example, to use different port {port: 4088}
  61   pscIdeServer: null, // purs ide server
  62   pscIdeServerArgs: {}, // for example, to change the port {port: 4088}
  63   pscIdeRebuildArgs: {} // for example, for sourcemaps {codegen: ['js', 'sourcemaps']}
  64   pscIdeColors: false, // defaults to true if psc === 'psa'
  65   pscPackage: false, // include dependencies from psc-package
  66   spago: false, // include dependencies from spago
  67   bundleOutput: 'output/bundle.js',
  68   bundleNamespace: 'PS',
  69   bundle: false,
  70   warnings: true,
  71   watch: false, // indicates if webpack is in watch mode
  72   output: 'output',
  73   src: [
  74     path.join('src', '**', '*.purs'),
  75     // if pscPackage = true
  76     // source paths reported by `psc-package sources`
  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')
  81   ]
  82 }
  83 ```
  84
  85 ### `psc-ide` support (experimental)
  86
  87 Experimental support for instant rebuilds using `psc-ide-server` can be enabled
  88 via the `pscIde: true` option.
  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
  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
  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
 102 ### Troubleshooting
 103
 104 #### Slower webpack startup after enabling psc-ide support?
 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
 112 #### Errors not being displayed in watch mode?
 113
 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 ```
 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
 138 `webpack --watch`, then ensure that all required binaries that the
 139 loader depends on are available in your `$PATH`.
 140
 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).
 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)