Skip to content

posthtml/posthtml-modules

Repository files navigation

NPM Deps Tests Coverage XO Code Style

Modules Plugin

Import and process HTML Modules with PostHTML

Install

npm i -D posthtml-modules

Example

<!-- index.html -->
<html>
<body>
  <module href="./module.html">
    title
  </module>
</body>
</html>
<!-- module.html -->
<header>
  <h1>
    Test <content></content>
  </h1>
</header>
const { readFileSync } = require('fs')
const posthtml = require('posthtml')
const options = { /* see available options below */ }

posthtml()
  .use(require('posthtml-modules')(options))
  .process(readFileSync('index.html', 'utf8'))
  .then((result) => result)
  });
<html>
 <body>
   <header>
     <h1>Test title</h1>
   </header>
  </body>
</html>

Options

root

Type: string
Default: ./

Root path for modules lookup.

plugins

Type: array | function
Default: []

PostHTML plugins to apply for every parsed module.

If a function provided, it will be called with module's file path.

from

Type: string
Default: ''

Root filename for processing apply, needed for path resolving (it's better to always provide it).

initial

Type: boolean
Default: false

Apply plugins to root file after modules processing.

tag

Type: string
Default: module

Use a custom tag name.

attribute

Type: string
Default: href

Use a custom attribute name.

locals

Type: object
Default: {}

Pass data to the module.

If present, the JSON object from the locals="" attribute will be merged on top of this, overwriting any existing values.

attributeAsLocals

Type: boolean
Default: false

All attributes on <module></module> will be added to locals

parser

Type: object
Default: {}

Options for the PostHTML parser.

By default, posthtml-parser is used.

expressions

Type: object
Default: {}

Options to forward to posthtml-expressions, like custom delimiters for example. Available options can be found here.

Component options

locals

You can pass data to a module using a locals="" attribute.

Must be a valid JSON object.

Example:

<!-- module.html -->
<p>The foo is {{ foo }} in this one.</p>
<content></content>
<!-- index.html -->
<module href="./module.html" locals='{"foo": "strong"}'>
  <p>Or so they say...</p>
</module>

Result

<p>The foo is strong in this one.</p>
<p>Or so they say...</p>

attributeAsLocals

All attributes on <module></module> will be added to locals

Example:

<!-- module.html -->
<div class="{{ class }}" id="{{ id }}" style="{{ style }}">
  <content></content>
</div>
<!-- index.html -->
<module 
  href="module.html" 
  class="text-center uppercase" 
  id="example"
  style="display: flex; gap: 2;"
>
  Module content
</module>

Result

<div class="text-center uppercase" id="example" style="display: flex; gap: 2;">
  Module content
</div>