Neurosis Prevention Mechanism
    Wondering what’s next for npm?Check out our public roadmap! »

    posthtml-hash
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.2 • Public • Published

    posthtml-hash

    NPM

    posthtml-hash is a PostHTML plugin for hashing file names to enable caching.

    <html>
      <head>
    -   <link rel="stylesheet" href="styles.[hash].css" />
    +   <link rel="stylesheet" href="styles.9a6cf95c41e87b9dc102.css" />
      </head>
      <body>
    -   <script src="src.[hash].js"></script>
    +   <script src="src.b0dcc67ffc1fd562f212.js"></script>
      </body>
    </html>

    Install

    yarn add -D posthtml-hash
    # OR 
    npm i -D posthtml-hash

    Usage

    Input

    By default, the plugin will attempt to hash file names that contain [hash]. As an additional qualifier, only nodes containing href, src, or content attributes are eligible.

    <html>
      <head>
        <!-- ✅ hashed -->
        <link rel="stylesheet" href="style.[hash].css" />
     
        <!-- ❌ not hashed -->
        <link rel="stylesheet" href="reset.css" />
      </head>
      <body>
        <!-- ✅ hashed -->
        <script src="src.[hash].js"></script> 
     
        <!-- ❌ not hashed -->
        <script src="analytics.js"></script> 
      </body>
    </html>

    Node.js

    The recommended usage of this plugin is to incorporate it in your post-build process.

    Let's say that you use Rollup to bundle and minify your CSS and JavaScript. The template index.html is copied to the build folder.

    // postbuild.js
    const fs = require("fs");
    const posthtml = require("posthtml");
    const { hash } = require("posthtml-hash");
     
    const html = fs.readFileSync("./build/index.html");
     
    posthtml()
      .use(hash({ path: "build" }))
      .process(html)
      .then((result) => fs.writeFileSync("./build/index.html", result.html));

    For convenience, you can add the post-build script to your package.json. The postbuild script is automatically invoked following the build script.

    {
      "scripts": {
        "build": "rollup -c",
        "postbuild": "node postbuild.js"
      }
    }

    Custom Hash Length

    Customize the hash length by specifying an integer after the hash:{NUMBER}. The default hash length is 20.

    Note: This only works for a pattern that uses square brackets and a colon separator. Use the hashLength option for different patterns.

    <script src="src.[hash].js"></script>
    <!-- src.b0dcc67ffc1fd562f212.js -->
     
    <script src="src.[hash:8].js"></script>
    <!-- src.b0dcc67f.js -->

    Options

    This plugin assumes that the file to process is in the same directory as the PostHTML script. If not, specify the relative path to the html file in options.path:

    hash({
      /**
       * Relative path to the HTML file being processed
       * @default ""
       */
      path: "public",
     
      /**
       * File name pattern (regular expression) to match
       * @default new RegExp(/\[hash.*]/g)
       */
      pattern: new RegExp(/custom-file-pattern/),
     
      /**
       * Hash length
       * @default 20
       */
      hashLength: 8,
     
      /**
       * Transform the href/src/content attribute value to a relative file path
       * @default (filepath) => filepath
       */
      transformPath: (filepath) => filepath.replace("https://example.com/", ""),
    });

    Recipes

    Custom Pattern and Hash Length

    hash({
      pattern: new RegExp(/custom-file-pattern/),
      hashLength: 8,
    });

    Result:

    - <script src="script.custom-file-pattern.js"></script>
    + <script src="script.b0dcc67f.js"></script>

    Remote origin URLs

    Input HTML:

    <head>
      <meta charset="utf-8" />
      <!-- We want to hash this image file name and preserve the remote origin URL -->
      <meta property="og:image" content="https://example.com/image.[hash].png" />
    </head>
    hash({
      transformPath: (filepath) => {
        // removes the targeted remote origin URL when looking up the files locally
        return filepath.replace("https://example.com/", "");
      },
    });

    Examples

    See the examples folder for end-to-end use cases.

    Contributing

    See the PostHTML Guidelines.

    Changelog

    License

    MIT

    Install

    npm i posthtml-hash

    DownloadsWeekly Downloads

    417

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    12.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar