EJS Templating Engine

Common errors

• ReferenceError: <variable_name> is not defined

  cause This typically occurs when EJS is running in strict mode (`strict: true`) or with `_with: false`, and template variables are accessed directly instead of through the `locals` object.
  fix In your template, change `<%= variable_name %>` to `<%= locals.variable_name %>`. Alternatively, ensure `strict: false` and `_with: true` are set in your EJS rendering options if direct variable access is desired.

• EJS: Could not find the include file "partial.ejs"

  cause EJS cannot resolve the path for an included template. This usually happens when the `filename` option is missing (needed for relative paths), or the `root` or `views` options are not correctly configured to specify template directories.
  fix When using `ejs.compile` or `ejs.render` with includes, provide the `filename` option with the absolute path of the current template. For Express, configure `app.set('views', path.join(__dirname, 'views'))` and ensure include paths are correct relative to these view directories.

• TypeError: ejs.filters is not a function

  cause You are attempting to use the `ejs.filters` global object, which was deprecated and completely removed in EJS v4.0.0.
  fix Remove any code referencing `ejs.filters`. Instead, pass custom helper functions as part of your template data object, or preprocess your data before passing it to EJS.

• Error: options.filename is required for caching

  cause You are attempting to use the `cache: true` option with `ejs.compile` or `ejs.render` without providing the `filename` option. EJS uses the `filename` as the key for its internal cache.
  fix Always provide the `filename` option with the absolute path to your template file when `cache: true` is enabled. For example, `ejs.render(str, data, { cache: true, filename: '/path/to/template.ejs' })`.

Warnings

• breaking The shortcut `ejs.render(dataAndOptions)` where all template data and rendering options are passed in a single object is officially deprecated and not recommended. It was effectively removed as a reliable pattern starting from v3.0.0 due to potential conflicts if an internal option name clashes with a data property name, leading to unpredictable behavior.
  Fix: Always use the explicit form `ejs.render(templateString, dataObject, optionsObject)` to clearly separate your template data from EJS rendering options.
• breaking The `ejs.filters` object, which provided a global mechanism for defining custom filter functions, was removed in EJS v4.0.0. Any code relying on `ejs.filters` will no longer function.
  Fix: Migrate away from `ejs.filters`. Implement custom logic as helper functions passed directly within your template data, or preprocess your data before rendering to apply transformations.
• breaking The `ejs.clearCache()` method, which allowed programmatic clearing of EJS's internal template cache, was removed in EJS v5.0.0. There is no direct public API to clear the cache anymore.
  Fix: If dynamic cache clearing is a critical requirement, you may need to reconsider your application's caching strategy, potentially by managing template compilation and caching manually or at a higher application level.
• gotcha EJS templates are essentially JavaScript runtimes. Directly passing unchecked user input (e.g., from `req.query`, `req.body`, or `req.params`) as the template string or influencing sensitive options like `filename`, `root`, or `closeDelimiter` can lead to severe Server-Side Template Injection (SSTI) and Remote Code Execution (RCE) vulnerabilities. The EJS project explicitly warns against this, stating that the `render` function is not intended for untrusted input.
  Fix: NEVER pass unsanitized user input directly to EJS template rendering functions or configuration options. Always rigorously validate and sanitize all external input. Treat any user-supplied template content as hostile and potentially malicious.
• gotcha By default, EJS uses JavaScript's `with()` statement (`_with: true`) to expose local variables directly in the template scope. However, when `strict: true` is enabled or `_with: false` is explicitly set, `with()` is not used. In these scenarios, template variables must be accessed via a `locals` object (e.g., `<%= locals.user.name %>` instead of `<%= user.name %>`), otherwise, a `ReferenceError` will occur.
  Fix: When using `strict: true` or `_with: false`, ensure all variables in your template are prefixed with `locals.` (e.g., `<%= locals.variableName %>`). Alternatively, explicitly set `_with: true` and `strict: false` if direct variable access is preferred and you understand the implications.

Install

• npm install ejs npm
• yarn add ejs yarn
• pnpm add ejs pnpm

Imports

• ejs
  wrong:

  const ejs = require('ejs');

  correct:

  import ejs from 'ejs';

  EJS supports both ES Modules (import) and CommonJS (require). Use the appropriate syntax for your project's module system. ESM is generally preferred in modern Node.js applications.
• ejs.render
  wrong:

  import { render } from 'ejs';
  const html = render(templateString, data, options);

  correct:

  import ejs from 'ejs';
  const html = ejs.render(templateString, data, options);

  The primary rendering functions like `render` and `compile` are properties of the default `ejs` import, not named exports. Access them directly from the imported `ejs` object.
• ejs.renderFile
  wrong:

  import { renderFile } from 'ejs';

  correct:

  import ejs from 'ejs';
  ejas.renderFile(filename, data, options, callback);

  `renderFile` is used for rendering templates from a file path. Like `render`, it is a method on the default `ejs` import, not a named export. It typically takes a callback function.

Quickstart

This quickstart demonstrates setting up EJS with an Express application to render templates from files and also shows how to render EJS template strings directly using `ejs.render`.

import ejs from 'ejs';
import express from 'express';
import path from 'path';

const app = express();
const port = process.env.PORT ?? 3000;

// Configure EJS as the view engine for Express
app.set('view engine', 'ejs');
app.set('views', path.join(__dirname, 'views'));

// Create a simple EJS template file (e.g., views/index.ejs):
// <!-- views/index.ejs -->
// <!DOCTYPE html>
// <html lang="en">
// <head>
//     <meta charset="UTF-8">
//     <meta name="viewport" content="width=device-width, initial-scale=1.0">
//     <title>EJS Example</title>
// </head>
// <body>
//     <h1>Hello, <%= user.name %>!</h1>
//     <% if (isAdmin) { %>
//         <p>You are an administrator.</p>
//     <% } else { %>
//         <p>Welcome, regular user.</p>
//     <% } %>
//     <p>Current time: <%= currentTime.toLocaleTimeString() %></p>
// </body>
// </html>

// Route to render a template file
app.get('/', (req, res) => {
  const userData = {
    user: { name: 'Alice' },
    isAdmin: true,
    currentTime: new Date()
  };
  res.render('index', userData);
});

// Route to render a template string directly
app.get('/direct', (req, res) => {
  const templateString = `<h2>Direct Render</h2><p>Server says: <%= message %></p>`;
  const data = { message: 'Hello from direct EJS render!' };
  const html = ejs.render(templateString, data);
  res.send(html);
});

app.listen(port, () => {
  console.log(`EJS example app listening at http://localhost:${port}`);
  console.log(`Try http://localhost:${port}/ and http://localhost:${port}/direct`);
});