{"id":11370,"library":"mustache","title":"Mustache.js - Logic-less Templates","description":"Mustache.js is a zero-dependency, logic-less templating engine for JavaScript, faithfully implementing the Mustache template system. Its current stable version is 4.2.0, with releases primarily focusing on bug fixes and minor enhancements. The library enables developers to utilize tag-based templates for a wide array of outputs, including HTML, configuration files, and source code, by expanding tags with values provided from a JavaScript object or hash. A key differentiator is its strict adherence to a 'logic-less' philosophy, meaning it explicitly avoids traditional control flow statements (like `if/else` or `for` loops), rendering content solely based on the presence or absence of data and iterating over arrays without explicit loops. Mustache.js offers broad compatibility, supporting CommonJS, AMD, and ECMAScript Modules, making it suitable for modern web browsers, Node.js server-side environments, and even as a command-line tool.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/janl/mustache.js","tags":["javascript","mustache","template","templates","ejs"],"install":[{"cmd":"npm install mustache","lang":"bash","label":"npm"},{"cmd":"yarn add mustache","lang":"bash","label":"yarn"},{"cmd":"pnpm add mustache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `Mustache` object is the default export in ESM. Named imports for the main object are incorrect.","wrong":"import { Mustache } from 'mustache';","symbol":"Mustache","correct":"import Mustache from 'mustache';"},{"note":"For CommonJS environments, the entire `Mustache` object is returned by `require`.","symbol":"Mustache (CommonJS)","correct":"const Mustache = require('mustache');"},{"note":"`render` is a method of the `Mustache` object, not a direct named export.","wrong":"import { render } from 'mustache';","symbol":"render","correct":"import Mustache from 'mustache';\nconst output = Mustache.render('{{foo}}', { foo: 'bar' });"},{"note":"When included directly via a `<script>` tag in a browser, `Mustache` is exposed as a global variable.","symbol":"Mustache (Global in Browser)","correct":"<script src=\"https://unpkg.com/mustache@latest\"></script>\n<script>\n  const output = Mustache.render('Hello {{name}}', { name: 'World' });\n</script>"}],"quickstart":{"code":"import Mustache from 'mustache';\nimport { readFileSync } from 'fs';\n\n// Basic usage\nconst view = {\n  title: 'My Title',\n  calc: () => 2 + 2,\n  name: 'World'\n};\nconst template = '<h1>{{title}}</h1><p>The answer is {{calc}}.</p><p>Hello, {{name}}!</p>';\nconst output = Mustache.render(template, view);\nconsole.log('Basic Render:\\n', output);\n\n// Using a template file (e.g., 'template.mustache')\n// Create a file named 'template.mustache' with content: 'User: {{username}}\\nEmail: {{email}}'\ntry {\n  const fileTemplate = readFileSync('template.mustache', 'utf8');\n  const fileView = { username: 'john.doe', email: 'john@example.com' };\n  const fileOutput = Mustache.render(fileTemplate, fileView);\n  console.log('\\nFile Render:\\n', fileOutput);\n} catch (error) {\n  console.warn('\\nCould not read template.mustache. Skipping file example.', error.message);\n  console.log('To run this part, create a file named `template.mustache` in the same directory with content:');\n  console.log(`User: {{username}}\\nEmail: {{email}}`);\n}\n\n// Example with partials (assuming a partial named 'greet' is available)\n// If you have a partials object: { greet: 'Hello {{name}}!' }\n// You could then use {{> greet}} in your main template.\nconst partialsView = { user: 'Alice' };\nconst mainTemplateWithPartial = 'Main template for {{user}}! {{> greet}}';\nconst partials = { greet: 'Welcome, {{user}}!' };\nconst partialOutput = Mustache.render(mainTemplateWithPartial, partialsView, partials);\nconsole.log('\\nRender with Partials:\\n', partialOutput);\n","lang":"typescript","description":"This quickstart demonstrates basic template rendering with a view object, rendering from a local file, and an example of using partials. It highlights the `Mustache.render` function."},"warnings":[{"fix":"Review the official Mustache.js v3.0.0 migration guide and thoroughly test your templates after upgrading.","message":"Version 3.0.0 introduced breaking changes, though the maintainers stated they were unlikely to affect most projects. Users upgrading from 2.x should review the official migration guide for potential 'unexpected rendering results'.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Pre-process your data object to include only the necessary values or computed properties. Implement helper functions in your view object that return processed data rather than embedding logic in templates.","message":"Mustache.js is strictly 'logic-less'. It does not support `if/else` statements, `for` loops, or complex JavaScript expressions within templates. All conditional logic or data transformations must occur in the 'view' (data object) before rendering.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Avoid custom template caching based on `Mustache.Writer.prototype.parse` if you are on affected versions, or ensure you are on a version that explicitly fixes or avoids this issue (e.g., 2.3.2 and later).","message":"Version 2.3.2 rolled back a template caching mechanism introduced in 2.3.1 due to 'unexpected behaviour' for several users. Relying on internal caching behavior could lead to inconsistent results or performance issues across versions.","severity":"breaking","affected_versions":">=2.3.1 <2.3.2"},{"fix":"Ensure your build tools (webpack, Rollup, etc.) and Node.js environment are compatible with `package.json` `exports`. For older Node.js, explicit paths like `require('mustache/mustache.js')` might be needed, though `require('mustache')` should generally work.","message":"The `package.json` `exports` field added in v4.2.0 improves ESM support but might affect how specific module bundlers or older Node.js versions (pre-12.x) resolve imports, potentially causing issues in mixed CJS/ESM environments if not correctly configured.","severity":"gotcha","affected_versions":">=4.2.0"},{"fix":"Upgrade to Mustache.js v3.1.0 or later to ensure correct partial indentation. If upgrading is not an option, manually adjust template formatting or post-process rendered output.","message":"Bugs related to indentation of partials were fixed in versions 3.0.2 and 3.1.0. Older versions might render partials with incorrect or unexpected indentation, especially with inline partials.","severity":"gotcha","affected_versions":"<3.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import Mustache from 'mustache';` (ESM), `const Mustache = require('mustache');` (CommonJS), or have included the script via `<script src=\"...\"></script>` in HTML, depending on your environment.","cause":"Attempting to use `Mustache.render` or other `Mustache` methods without correctly importing or loading the library in an ESM, CommonJS, or browser global context.","error":"ReferenceError: Mustache is not defined"},{"fix":"Access `render` as a property of the `Mustache` object: `import Mustache from 'mustache'; Mustache.render(...)`. The `render` function is not a direct named export.","cause":"Often happens when attempting to destructure `render` as a named import (e.g., `import { render } from 'mustache'`) instead of accessing it from the default `Mustache` object.","error":"TypeError: Cannot read properties of undefined (reading 'render') OR TypeError: Mustache.render is not a function"},{"fix":"Verify partial syntax (`{{> partial_name}}`). Ensure the `partials` object passed to `Mustache.render` contains the required templates. If using an older version, upgrade to v3.1.0 or newer to address known indentation bugs.","cause":"This can be due to incorrect partial syntax, missing partials in the `partials` argument to `Mustache.render`, or historical bugs in older versions related to partial indentation.","error":"Partials are not rendering, or have incorrect indentation."}],"ecosystem":"npm"}