Reshape Webpack Loader

A reshape loader for webpack

Installation

npm i reshape-loader --save

Compatibility

This loader is only compatible with webpack 2. If you want to use it for webpack 1, you can install version 0.4.2 and checkout the webpack1 branch for the readme and docs.

Usage

There are two distinct ways you can use this loader. By default, it will compile your templates and return a function which you can get by require-ing the original template path. It can also produce static html if used with the locals option.

Options are passed through the options parameter of the reshape loader rule. It's important to note that the value of options must be an object, so it cannot be a function as was used in previous webpack versions.

A basic configuration example:

// webpack.config.js
module.exports = {
  module: {
    rules: [{
      test: /\.html$/,
      loader: 'reshape-loader',
      options: { plugins: [/* plugins here */] }
    }]
  }
}

There are a couple differences between the configuration that can be passed through this loader, and to reshape directly. First, the plugins option must be an array. If you have a single plugin, it cannot be passed as the value of plugins, it needs to be contained within an array. Second, any of the options can instead be functions that return the value you want the option to be when called. The loader will execute the functions, passing in webpack's loader context as the first argument. For the generator and parser options, which are expected to be functions anyway, you must attach a convert property to the function if you intend to pass a function that returns your parser/generator rather than the parser/generator itself.

A more advanced example:

// webpack.config.js
const somePlugin = require('./somePlugin')
const parser = require('reshape-parser')
const sugarml = require('sugarml')

function parserFn (loaderContext) {
  return loaderContext.resourcePath.match(/\.sgr$/) ? sugarml : parser
}
parserFn.convert = true

module.exports = {
  module: {
    rules: [{
      test: /\.html$/,
      loader: 'reshape-loader',
      options: {
        plugins: (loaderContext) => {
          return [somePlugin({ file: loaderContext.resourcePath })]
        },
        parser: parserFn
      }
    }]
  }
}

Note that the above example is pseudo-code, it will not work if copy/pasted directly. It's just intended to give an idea of how some of the more advanced configuration options might be used.

Producing Static HTML

Reshape produces a function as its output by default, however some use-cases call for returning the static html as the output. If this is necessary, you can use the locals argument along with any params you want to pass to the function (such a local variables) to have reshape-loader export a compiled html string. For example:

<p>Hello {{ planet }}!</p>

// webpack.config.js
const expressions = require('reshape-expressions')

module.exports = {
  module: {
    rules: [{
      test: /\.html$/,
      use: [
        { loader: 'source-loader' },
        {
          loader: 'reshape-loader',
          options: {
            plugins: [expressions()],
            locals: { planet: 'world' }
          }
        }
      ]
    }]
  }
}

const html = require('./index.html')
console.log(html) // <p>Hello world!</p>

If you do this, you will want at least one other loader in order to integrate the returned source with webpack correctly. For most use cases, the html-loader is recommended. If you want to export the html string directly for use in javascript or webpack plugins, we recommend the source-loader. Whichever loader you choose, it should be the first loader, followed by reshape, as seen in the example above.

Producing Multiple Outputs from a Single File

The reshape loader is unique in its ability to take in a single source file, and compile multiple outputs with different options for each output. This ability can be very useful for cases in which a single template is used with a set of different locals to produce variants purely from a data input, such as for internationalization.

In order to use multiple outputs, you can pass the multi option. This option should be an array of objects, each one will be merged with the base options (with priority given to the multi object), and used to produce a unique output. It is required that each multi object contains a name property, which is used to name the output. So for example, if we wanted to produce a static html result with a single template compiled with two different languages, it might look like this:

<!-- index.html -->
<p>{{ greeting }}!</p>

// webpack.config.js
module.exports = {
  module: {
    rules: [{
      test: /\.html$/,
      use: [
        { loader: 'source-loader' },
        {
          loader: 'reshape-loader',
          options: {
            multi: [
              { locals: { greeting: 'hello' }, name: 'en' },
              { locals: { greeting: 'hola' }, name: 'es' }
            ]
          }
        }
      ]
    }]
  }
}

const html = require('./index.html')
console.log(html) // { en: "<p>hello!</p>", es: "<p>hola!</p>" }

It should be noted that passing in anything as the multi option will return static html, regardless of any other options. If you want to use a template, you don't need the multi option, you can just execute the template with different sets of locals on the client side as needed.

Custom Plugin Hooks

Reshape loader adds a custom hook that webpack plugins can utilize called beforeLoaderCompile (sync). This hook exposes the options as they stand immediately before being passed to reshape for compilation, allowing them to be read and/or modified by plugins. For example, if you wanted to make a plugin that adds a test key to the locals, it might look like this.

module.exports = class TestPlugin {
  apply (compiler) {
    compiler.plugin('beforeLoaderCompile', (options) => {
      Object.assign(options, { test: 'wow' })
    })
  }
}

License & Contributing

• Licensed under MIT
• See contributing guidelines