All Versions
Latest Version
Avg Release Cycle
100 days
Latest Release

Changelog History
Page 1

  • v13.2.0

    // index.mjs
    import mustache from 'mustache/mustache.mjs'
    console.log(mustache.render('Hello {{name}}!', { name: 'Santa' }))
    // Hello Santa!

    ES Module support for Node.js will be improved in the future when Conditional Exports 0️⃣ is enabled by default rather than being behind an experimental flag.

    📄 More info in Node.js ECMAScript Modules docs.

  • v4.0.1

    March 15, 2020

    🛠 Fixed

    • [#739]: Fix custom delimiters in nested partials, by [@aielo].
  • v4.0.0

    January 16, 2020

    Majority of using projects don't have to worry by this being a new major version.

    TLDR; if your project manipulates Writer.prototype.parse | Writer.cache directly or uses .to_html(), you probably have to change that code.

    🚀 This release allows the internal template cache to be customised, either by disabling it completely 📜 or provide a custom strategy deciding how the cache should behave when mustache.js parses templates.

    const mustache = require('mustache');
    // disable caching
    Mustache.templateCache = undefined;
    // or use a built-in Map in modern environments
    Mustache.templateCache = new Map();

    Projects that wanted to customise the caching behaviour in earlier versions of mustache.js were forced to 📜 override internal method responsible for parsing templates; Writer.prototype.parse. In short, that was unfortunate because there is more than caching happening in that method.

    We've improved that now by introducing a first class API that only affects template caching.

    0️⃣ The default template cache behaves as before and is still compatible with older JavaScript environments. For those who wants to provide a custom more sopisiticated caching strategy, one can do that with an object that adheres to the following requirements:

      set(cacheKey: string, value: string): void
      get(cacheKey: string): string | undefined
      clear(): void

    ➕ Added

    • [#731]: Allow template caching to be customised, by [@AndrewLeedham].

    ✂ Removed

    • 🚚 [#735]: Remove .to_html(), by [@phillipj].
  • v3.2.1

    December 30, 2019

    🛠 Fixed

    • [#733]: Allow the CLI to use JavaScript views when the project has ES6 modules enabled, by [@eobrain].
  • v3.2.0

    December 18, 2019

    ➕ Added

    • [#728]: Expose ECMAScript Module in addition to UMD (CommonJS, AMD & global scope), by [@phillipj] and [@zekth].

    Using mustache.js as an ES module

    0️⃣ To stay backwards compatible with already using projects, the default exposed module format is still UMD. That means projects using mustache.js as an CommonJS, AMD or global scope module, from npm or directly from can keep on doing that for now.

    For those projects who would rather want to use mustache.js as an ES module, the mustache/mustache.mjs file has to be imported directly.

    Below are some usage scenarios for different runtimes.

    💻 Modern browser with ES module support

    <!-- index.html -->
    <script type="module">
      import mustache from ""
      console.log(mustache.render('Hello {{name}}!', { name: 'Santa' }))
      // Hello Santa!
  • v3.1.0

    September 13, 2019

    ➕ Added

    • 👍 #717: Added support .js files as views in command line tool, by @JEStaubach.

    🛠 Fixed

  • v3.0.3

    August 27, 2019

    ➕ Added

    • [#713]: Add test cases for custom functions in partials, by [@wol-soft].

    🛠 Fixed

    • [#714]: Bugfix for wrong function output in partials with indentation, by [@phillipj].
  • v3.0.2

    August 21, 2019

    🛠 Fixed


    • #701: Fix test failure for Node 10 and above, by @andersk.
    • 👕 #704: Lint all test files just like the source files, by @phillipj.
    • Start experimenting & comparing GitHub Actions vs Travis CI, by @phillipj.
  • v3.0.1

    November 11, 2018

    #679: Fix partials not rendering tokens when using custom tags, by @stackchain.

  • v3.0.0

    September 16, 2018

    3.0.0 / 16 September 2018

    We are very happy to announce a new major version of mustache.js. We want to be very careful not to break projects out in the wild, and adhering to Semantic Versioning we have therefore cut this new major version.

    The changes introduced will likely not require any actions for most using projects. The things to look out
    for that might cause unexpected rendering results are described in the migration guide below.

    🚀 A big shout out and thanks to @raymond-lam for this release! Without his contributions with code and
    🚀 issue triaging, this release would never have happened.


    • #618: Allow rendering properties of primitive types that are not objects, by @raymond-lam.
    • 📜 #643: Writer.prototype.parse to cache by tags in addition to template string, by @raymond-lam.
    • 📜 #664: Fix Writer.prototype.parse cache, by @seminaoki.


    Migrating from mustache.js v2.x to v3.x

    Rendering properties of primitive types

    We have ensured properties of primitive types can be rendered at all times. That means Array.length, String.length and similar. A corner case where this could cause unexpected output follows:


      stooges: [
        { name: "Moe" },
        { name: "Larry" },
        { name: "Curly" }


      {{name}}: {{name.length}} characters

    Output with v3.0:

      Moe: 3 characters
      Larry: 5 characters
      Curly: 5 characters

    Output with v2.x:

      Moe: characters
      Larry: characters
      Curly: characters

    Caching for templates with custom delimiters

    We have improved the templates cache to ensure custom delimiters are taken into consideration for the
    cache. This improvement might cause unexpected rendering behaviour for using projects actively using the custom delimiters functionality.

    📜 Previously it was possible to use Mustache.parse() as a means to set global custom delimiters. If custom
    delimiters were provided as an argument, it would affect all following calls to Mustache.render().
    Consider the following:

    const template = "[[item.title]] [[item.value]]";mustache.parse(template, ["[[", "]]"]);console.log( mustache.render(template, { item: { title: "TEST", value: 1 } }) );\>\> TEST 1

    📜 The above illustrates the fact that Mustache.parse() made mustache.js cache the template without
    considering the custom delimiters provided. This is no longer true.

    📜 We no longer encourage using Mustache.parse() for this purpose, but have rather added a fourth argument to Mustache.render() letting you provide custom delimiters when rendering.

    📜 If you still need the pre-parse the template and use custom delimiters at the same time, ensure to provide
    the custom delimiters as argument to Mustache.render() as well.