String
+PostHTML Loader
+
+**Kind**: global function
+**Returns**: String - html HTML
+**Requires**: module:loader-utils, module:schema-utils, module:posthtml, module:posthtml-load-config
+**Version**: 1.0.0
+**Author**: Michael Ciniawsky String | HTML |
+
diff --git a/README.md b/README.md
index 9657289..2abc27e 100644
--- a/README.md
+++ b/README.md
@@ -1,112 +1,244 @@
-# PostHTML Loader 
-
[![npm][npm]][npm-url]
-[![tests][travis]][travis-url]
-[![dependencies][deps]][deps-url]
+[![node][node]][node-url]
+[![deps][deps]][deps-url]
+[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
-[![Code Style][style]][style-url]
+[![code style][style]][style-url]
+[![chat][chat]][chat-url]
-A PostHTML loader for webpack
+
-## Installation
+
+ Install
-```sh -npm i html-loader posthtml-loader --save +```bash +npm i -D posthtml-loader ``` -## Usage - -The posthtml loader must be used with at least one other loader in order to integrate with webpack correctly. For most use cases, the [html-loader](https://github.com/webpack/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](https://github.com/static-dev/source-loader). Whichever loader you choose, it should be the first loader, followed by posthtml, as you will see in the examples below. - -Options can be passed through a `posthtml` option directly on the webpack config object. It accepts an array, an object, or a function that returns an array or object. If it's an array, it should contain plugins. If it's an object, it can contain a `plugins` key, which is an array of plugins and an optional `parser` key which allows you to pass in a custom parser. Any other key will apply to the `pack` querystring parameter, documented below. +Usage
-Basic configuration example: +```js +import html from './file.html' +``` +**webpack.config.js** ```js -// webpack.config.js module: { - loaders: [{ - test: /\.html$/, - loader: 'html!posthtml' - }] + rules: [ + { + test: /\.html$/, + use: [ + 'html-loader', + { + loader: 'posthtml-loader', + options: { + ident: 'posthtml', + parser: 'PostHTML Parser' + plugins: [ + /* PostHTML Plugins */ + require('posthtml-plugin')(options) + ] + } + } + ] + } + ] }, -posthtml: [/* plugins here */] ``` -### Plugin Packs +Options
+ +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|**[`config`](#config)**|`{Object}`|`undefined`|PostHTML Config| +|**[`parser`](#parser)**|`{String/Function}`|`undefined`|PostHTML Parser| +|**[`plugins`](#plugins)**|`{Array/Function}`|`[]`|PostHTML Plugins| -If you need to apply different sets of plugins to different groups of files, you can use a **plugin pack**. Just add `pack=[name]` as a querystring option, and return an object from the `posthtml` config option with a key matching the pack name, and the value being an array of plugins. +### `Config` + +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|**[`path`](#path)**|`{String}`|`loader.resourcePath`|PostHTML Config Path| +|**[`ctx`](#context)**|`{Object}`|`{}`|PostHTML Config Context| + +If you want to use are shareable config file instead of inline options in your `webpack.config.js` create a `posthtml.config.js` file and placed it somewhere down the file tree in your project. The nearest config relative to `dirname(file)` currently processed by the loader applies. This enables **Config Cascading**. Despite some edge cases the config file will be loaded automatically and **no** additional setup is required. If you don't intend to use Config Cascading, it's recommended to place `posthtml.config.js` in the **root** `./` of your project + +``` +|â src +||â components +|||â component.html +|||â posthtml.config.js (components) +||â index.html +| +|â posthtml.config.js (index) +|â webpack.config.js +``` +#### `Path` + +If you normally place all your config files in a separate folder e.g `./config` it is necessary to explicitly set the config path in `webpack.config.js` + +**webpack.config.js** ```js -// webpack.config.js -module: { - loaders: [{ - test: /\\.special\.html$/, - loader: 'html!posthtml?pack=special' - }] -}, -posthtml: { - plugins: [/* plugins that apply anything that's not using a pack */], - special: [ /* plugins specific to the "special" pack */ ], +{ + loader: 'posthtml-loader', + options: { + config: { + path: 'path/to/.config/' + } + } } ``` -### Using a Function +#### `Context` -You can also return a function from the `posthtml` config value, if you need to for any reason. The function passes along the [loader context](https://webpack.github.io/docs/loaders.html#loader-context) as an argument, so you can get information about the file currently being processed from this and pass it to plugins if needed. For example: +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|`env`|`{String}`|`'development'`|process.env.NODE_ENV| +|`file`|`{Object}`|`{ dirname, basename, extname }`|File| +|`options`|`{Object}`|`{}`|Plugin Options (Context)| +[**posthtml.config.js**](https://github.com/posthtml/posthtml-load-config) ```js -// webpack.config.js -module: { - loaders: [{ - test: /\.html$/, - loader: 'html!posthtml' - }] -}, -posthtml: (ctx) => { - return [examplePlugin({ filename: ctx.resourcePath })] +module.exports = ({ file, options, env }) => ({ + parser: 'posthtml-sugarml' + plugins: { + 'posthtml-include': options.include + 'posthtml-content': options.content + 'htmlnano': env === 'production' ? {} : false + } +}) +``` + +**webpack.config.js** +```js +{ + loader: 'posthtml-loader', + options: { + config: { + ctx: { + include: {...options} + content: {...options} + } + } + } +} +``` + +### `Parser` + +If you want to use a custom parser e.g [SugarML](https://github.com/posthtml/sugarml), you can pass it in under the `parser` key in the loader options + +#### `{String}` + +**webpack.config.js** +```js +{ + loader: 'posthtml-loader', + options: { + parser: 'posthtml-sugarml' + } +} +``` + +#### `{Function}` + +**webpack.config.js** +```js +{ + loader: 'posthtml-loader', + options: { + parser: require('posthtml-sugarml')() + } } ``` -### Custom Parser +### `Plugins` -If you want to use a custom parser, you can pass it in under the `parser` key. Below is an example with the [sugarml parser](https://github.com/posthtml/sugarml): +Plugins are specified under the `plugins` key in the loader options +#### `{Array}` + +**webpack.config.js** ```js -// webpack.config.js -const sugarml = require('sugarml') +{ + loader: 'posthtml-loader', + options: { + plugins: [ + require('posthtml-plugin')() + ] + } +} +``` -module: { - loaders: [{ - test: /\\.special\.html$/, - loader: 'html!posthtml?pack=special' - }] -}, -posthtml: { - plugins: [/* posthtml plugins */], - parser: sugarml +#### `{Function}` + +**webpack.config.js** +```js +{ + loader: 'posthtml-loader', + options: { + plugins (loader) { + return [ + require('posthtml-plugin')() + ] + } + } } ``` -## License & Contributing +Maintainer
+ +
+ 
+ + Michael Ciniawsky + |
+
Contributors
+ +
+ 
+ + Ivan Demidov + |
+
Hello
diff --git a/test/fixtures/fixture.js b/test/fixtures/fixture.js
new file mode 100644
index 0000000..d61d7d7
--- /dev/null
+++ b/test/fixtures/fixture.js
@@ -0,0 +1 @@
+import html from './fixture.html'
diff --git a/test/fixtures/locals/app.js b/test/fixtures/locals/app.js
deleted file mode 100644
index 01a7563..0000000
--- a/test/fixtures/locals/app.js
+++ /dev/null
@@ -1 +0,0 @@
-require('./index.html')
diff --git a/test/fixtures/locals/index.html b/test/fixtures/locals/index.html
deleted file mode 100644
index 13db462..0000000
--- a/test/fixtures/locals/index.html
+++ /dev/null
@@ -1 +0,0 @@
-{{ foo }}
diff --git a/test/fixtures/options/config/posthtml.config.js b/test/fixtures/options/config/posthtml.config.js new file mode 100644 index 0000000..52eec8c --- /dev/null +++ b/test/fixtures/options/config/posthtml.config.js @@ -0,0 +1,7 @@ +module.exports = (ctx) => ({ + to: 'delete.html', + from: 'delete.html', + plugins: [ + ctx.options.plugin ? require('../../plugin')() : false + ] +}) diff --git a/test/fixtures/options/parser/fixture.js b/test/fixtures/options/parser/fixture.js new file mode 100644 index 0000000..fc67d60 --- /dev/null +++ b/test/fixtures/options/parser/fixture.js @@ -0,0 +1 @@ +import html from './fixture.ssml' diff --git a/test/fixtures/options/parser/fixture.ssml b/test/fixtures/options/parser/fixture.ssml new file mode 100644 index 0000000..e115573 --- /dev/null +++ b/test/fixtures/options/parser/fixture.ssml @@ -0,0 +1 @@ +div Hello diff --git a/test/fixtures/plugin.js b/test/fixtures/plugin.js new file mode 100644 index 0000000..6896202 --- /dev/null +++ b/test/fixtures/plugin.js @@ -0,0 +1,15 @@ +'use strict' + +module.exports = function plugin (options) { + options = Object.assign({}, options) + + return function (tree) { + tree.walk((node) => { + if (node.tag === 'div') node.tag = 'section' + + return node + }) + + return tree + } +} diff --git a/test/fixtures/posthtml.config.js b/test/fixtures/posthtml.config.js new file mode 100644 index 0000000..e2b0f4b --- /dev/null +++ b/test/fixtures/posthtml.config.js @@ -0,0 +1,5 @@ +module.exports = { + plugins: [ + require('./plugin')() + ] +} diff --git a/test/helpers/compiler.js b/test/helpers/compiler.js new file mode 100644 index 0000000..9add1dd --- /dev/null +++ b/test/helpers/compiler.js @@ -0,0 +1,67 @@ +'use strict' + +const path = require('path') +const del = require('del') +const webpack = require('webpack') +const MemoryFS = require('memory-fs') + +const modules = (config) => { + return { + rules: config.rules + ? config.rules + : config.loader + ? [ + { + test: config.loader.test || /\.txt$/, + use: { + loader: path.resolve(__dirname, '../../lib'), + options: config.loader.options || {} + } + } + ] + : [] + } +} + +const plugins = config => ([ + new webpack.optimize.CommonsChunkPlugin({ + names: ['runtime'], + minChunks: Infinity + }) +].concat(config.plugins || [])) + +const output = (config) => { + return { + path: path.resolve( + __dirname, + `../outputs/${config.output ? config.output : ''}` + ), + filename: '[name].js', + chunkFilename: '[name].chunk.js' + } +} + +module.exports = function (fixture, config, options) { + config = { + devtool: config.devtool || 'sourcemap', + context: path.resolve(__dirname, '..', 'fixtures'), + entry: `./${fixture}`, + output: output(config), + module: modules(config), + plugins: plugins(config) + } + + options = Object.assign({ output: false }, options) + + if (options.output) del.sync(config.output.path) + + const compiler = webpack(config) + + if (!options.output) compiler.outputFileSystem = new MemoryFS() + + return new Promise((resolve, reject) => compiler.run((err, stats) => { + if (err) reject(err) + + resolve(stats) + })) +} diff --git a/test/index.js b/test/index.js deleted file mode 100644 index 4ec629e..0000000 --- a/test/index.js +++ /dev/null @@ -1,89 +0,0 @@ -const test = require('ava') -const webpack = require('webpack') -const path = require('path') -const fs = require('fs') -const node = require('when/node') -const customElements = require('posthtml-custom-elements') -const exp = require('posthtml-exp') -const sugarml = require('sugarml') -const fixtures = path.join(__dirname, 'fixtures') - -test('basic', (t) => { - return webpackCompile('basic', [customElements()]) - .then(({outputPath, src}) => { - t.truthy(src.match(/hello world<\/div>/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('config function', (t) => {
- return webpackCompile('basic', () => [customElements()])
- .then(({outputPath, src}) => {
- t.truthy(src.match(/
hello world<\/div>/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('config object', (t) => {
- return webpackCompile('basic', { plugins: [customElements()] })
- .then(({outputPath, src}) => {
- t.truthy(src.match(/
hello world<\/div>/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('plugin packs', (t) => {
- return webpackCompile('basic', { special: [customElements()] }, '?pack=special')
- .then(({outputPath, src}) => {
- t.truthy(src.match(/
hello world<\/div>/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('custom parser', (t) => {
- return webpackCompile('custom_parser', {
- plugins: [customElements()],
- parser: sugarml
- }).then(({outputPath, src}) => {
- t.truthy(src.match(/
hello world<\/div>/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('invalid config', (t) => {
- return webpackCompile('custom_parser', 5)
- .then(() => t.fail('invalid config, no error'))
- .catch(({outputPath, err}) => {
- t.truthy(err.toString().match(/Error: Configuration must return an array or object/))
- fs.unlinkSync(outputPath)
- })
-})
-
-test('function called with correct context', (t) => {
- return webpackCompile('locals', (ctx) => {
- return [exp({ locals: { foo: ctx.resourcePath } })]
- }).then(({outputPath, src}) => {
- t.truthy(src.match(/test\/fixtures\/locals\/index\.html/))
- fs.unlinkSync(outputPath)
- })
-})
-
-// Utility: compile a fixture with webpack, return results
-function webpackCompile (name, config, qs = '') {
- const testPath = path.join(fixtures, name)
- const outputPath = path.join(testPath, 'bundle.js')
-
- return node.call(webpack, {
- entry: { output: [path.join(testPath, 'app.js')] },
- output: { path: testPath },
- resolveLoader: { root: path.resolve('../lib') },
- module: {
- loaders: [{ test: /\.html$/, loader: `source!index${qs}` }]
- },
- posthtml: config
- }).then((stats) => {
- if (stats.compilation.errors.length) throw stats.compilation.errors
- const src = fs.readFileSync(outputPath, 'utf8')
- return {outputPath, src}
- }).catch((err) => { throw {outputPath, err} }) // eslint-disable-line
-}
diff --git a/test/loader.test.js b/test/loader.test.js
new file mode 100644
index 0000000..ff14a9f
--- /dev/null
+++ b/test/loader.test.js
@@ -0,0 +1,22 @@
+'use strict'
+
+const webpack = require('./helpers/compiler')
+
+describe('Loader', () => {
+ test('Defaults', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {}
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+})
diff --git a/test/options/__snapshots__/config.test.js.snap b/test/options/__snapshots__/config.test.js.snap
new file mode 100644
index 0000000..b721f8a
--- /dev/null
+++ b/test/options/__snapshots__/config.test.js.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Options config ctx - {Object} 1`] = `
+"export default \`Hello
+\`"
+`;
+
+exports[`Options config path - {String} 1`] = `
+"export default \`Hello
+\`"
+`;
diff --git a/test/options/__snapshots__/parser.test.js.snap b/test/options/__snapshots__/parser.test.js.snap
new file mode 100644
index 0000000..b106d4d
--- /dev/null
+++ b/test/options/__snapshots__/parser.test.js.snap
@@ -0,0 +1,5 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Options parser {Object} 1`] = `"export default \`Hello
+\`"
+`;
+
+exports[`Options plugins {Function} - {Array} 1`] = `
+"export default \`Hello
+\`"
+`;
+
+exports[`Options plugins {Function} - {Object} 1`] = `
+"export default \`Hello
+\`"
+`;
diff --git a/test/options/config.test.js b/test/options/config.test.js
new file mode 100644
index 0000000..5aecd0d
--- /dev/null
+++ b/test/options/config.test.js
@@ -0,0 +1,50 @@
+'use strict'
+
+const webpack = require('../helpers/compiler')
+
+describe('Options', () => {
+ describe('config', () => {
+ test('path - {String}', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {
+ config: {
+ path: 'test/fixtures/posthtml.config.js'
+ }
+ }
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+
+ test('ctx - {Object}', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {
+ config: {
+ path: 'test/fixtures/options/config/posthtml.config.js',
+ ctx: { plugin: true }
+ }
+ }
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+ })
+})
diff --git a/test/options/parser.test.js b/test/options/parser.test.js
new file mode 100644
index 0000000..cc83546
--- /dev/null
+++ b/test/options/parser.test.js
@@ -0,0 +1,45 @@
+'use strict'
+
+const webpack = require('../helpers/compiler')
+
+describe('Options', () => {
+ describe('parser', () => {
+ test('{String}', () => {
+ const config = {
+ loader: {
+ test: /\.ssml$/,
+ options: {
+ parser: 'posthtml-sugarml'
+ }
+ }
+ }
+
+ return webpack('options/parser/fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+
+ test('{Object}', () => {
+ const config = {
+ loader: {
+ test: /\.ssml$/,
+ options: {
+ parser: require('posthtml-sugarml')()
+ }
+ }
+ }
+
+ return webpack('options/parser/fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+ })
+})
diff --git a/test/options/plugins.test.js b/test/options/plugins.test.js
new file mode 100644
index 0000000..36023e7
--- /dev/null
+++ b/test/options/plugins.test.js
@@ -0,0 +1,75 @@
+'use strict'
+
+const webpack = require('../helpers/compiler')
+
+describe('Options', () => {
+ describe('plugins', () => {
+ test('{Array}', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {
+ ident: 'posthtml',
+ plugins: [
+ require('../fixtures/plugin')()
+ ]
+ }
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+
+ test('{Function} - {Array}', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {
+ ident: 'posthtml',
+ plugins () {
+ return [
+ require('../fixtures/plugin')()
+ ]
+ }
+ }
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+
+ test('{Function} - {Object}', () => {
+ const config = {
+ loader: {
+ test: /\.html$/,
+ options: {
+ ident: 'posthtml',
+ plugins () {
+ return require('../fixtures/plugin')()
+ }
+ }
+ }
+ }
+
+ return webpack('fixture.js', config)
+ .then((stats) => {
+ const module = stats.toJson().modules[1]
+
+ expect(module.source).toMatchSnapshot()
+ })
+ .catch((err) => err)
+ })
+ })
+})
Hello
\`"`;
+
+exports[`Options parser {String} 1`] = `"export default \`Hello
\`"`;
diff --git a/test/options/__snapshots__/plugins.test.js.snap b/test/options/__snapshots__/plugins.test.js.snap
new file mode 100644
index 0000000..3ad6b08
--- /dev/null
+++ b/test/options/__snapshots__/plugins.test.js.snap
@@ -0,0 +1,16 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Options plugins {Array} 1`] = `
+"export default \`