Introduction to EJS

Philosophy: "Just JavaScript"

EJS stands for Embedded JavaScript. Created by TJ Holowaychuk in 2010 as part of the Express.js ecosystem. Unlike Pug or Handlebars, EJS uses plain HTML with embedded JS — no new syntax to learn.

What Gets Escaped

// EJS internal escape function
function escape(s) {
  return String(s)
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

if / else if / else

<% if (user.role === 'admin') { %>
  <div class="badge admin">Admin</div>
<% } else if (user.role === 'editor') { %>
  <div class="badge editor">Editor</div>
<% } else { %>
  <div class="badge member">Member</div>
<% } %>

forEach (Most Common)

<ul>
  <% users.forEach(user => { %>
    <li>
      <%= user.name %>
      — <%= user.email %>
    </li>
  <% }) %>
</ul>

Express res.render()

// Route handler
app.get('/dashboard', async (req, res) => {
  const user = await User.findById(req.user.id);
  const stats = await getStats(user.id);

  res.render('dashboard', {
    title: 'Dashboard',
    user,
    stats,
    isAdmin: user.role === 'admin',
    formatDate: (d) =>
      d.toLocaleDateString('en-GB')
  });
});

Manual Layout with Includes

<!-- views/pages/home.ejs -->
<%- include('../partials/head', {
  title: 'Home'
}) %>
<%- include('../partials/nav') %>

<main class="container">
  <h1>Welcome, <%= user.name %></h1>
  <p><%= tagline %></p>
</main>

<%- include('../partials/footer') %>

Simple but repetitive — every page repeats the include boilerplate.

Basic include Syntax

<!-- No data passed -->
<%- include('partials/nav') %>

<!-- Pass data to partial -->
<%- include('partials/card', {
  title: product.name,
  price: product.price,
  image: product.imageUrl
}) %>

Important: Use <%- %> (unescaped) for includes. Using <%= %> would escape the HTML output of the partial.

Passing Helper Functions

// helpers/format.js
module.exports = {
  currency: (n, curr = 'GBP') =>
    new Intl.NumberFormat('en-GB', {
      style: 'currency', currency: curr
    }).format(n),

  dateShort: (d) =>
    new Date(d).toLocaleDateString(
      'en-GB',
      { day: 'numeric', month: 'short',
        year: 'numeric' }
    ),

  truncate: (str, len = 100) =>
    str.length > len
      ? str.slice(0, len) + '...'
      : str,

  pluralise: (count, word) =>
    `${count} ${word}${count !== 1 ? 's' : ''}`
};

Rendering a Form

<form action="/register" method="POST">
  <input type="hidden"
    name="_csrf"
    value="<%= csrfToken %>">

  <label for="name">Name</label>
  <input type="text" id="name"
    name="name"
    value="<%= form.name || '' %>"
    class="<%= errors?.name
      ? 'is-invalid' : '' %>">
  <% if (errors?.name) { %>
    <span class="error">
      <%= errors.name.msg %>
    </span>
  <% } %>

  <label for="email">Email</label>
  <input type="email" id="email"
    name="email"
    value="<%= form.email || '' %>">

  <button type="submit">Register</button>
</form>

Rule of Thumb

Defensive Template Coding

<!-- Use defaults to avoid crashes -->
<%= typeof title !== 'undefined'
    ? title : 'Default Title' %>

<!-- Optional chaining -->
<%= user?.profile?.avatar ?? '/img/default.png' %>

<!-- locals object (Express) -->
<%= locals.title || 'Fallback' %>

How EJS Compiles Templates

Parsing is the expensive step. Once compiled, the JS function is reused. The cache option stores compiled functions in memory.

Directory Layout

my-app/
├── app.js
├── package.json
├── .env
├── config/
│   └── db.js
├── routes/
│   ├── index.js
│   ├── auth.js
│   └── products.js
├── controllers/
│   ├── authController.js
│   └── productController.js
├── models/
│   ├── User.js
│   └── Product.js
├── middleware/
│   ├── auth.js
│   └── validate.js
├── helpers/
│   └── format.js
├── views/
│   ├── layouts/
│   │   └── main.ejs
│   ├── partials/
│   │   ├── head.ejs
│   │   ├── nav.ejs
│   │   ├── flash.ejs
│   │   └── footer.ejs
│   ├── pages/
│   │   ├── home.ejs
│   │   ├── about.ejs
│   │   └── contact.ejs
│   ├── auth/
│   │   ├── login.ejs
│   │   └── register.ejs
│   ├── products/
│   │   ├── index.ejs
│   │   ├── show.ejs
│   │   └── edit.ejs
│   └── error.ejs
└── public/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/

app.js — Full Express + EJS App

const express = require('express');
const ejsLayouts = require(
  'express-ejs-layouts'
);
const path = require('path');
const app = express();

app.set('view engine', 'ejs');
app.set('views',
  path.join(__dirname, 'views'));
app.use(ejsLayouts);
app.set('layout', 'layouts/main');
app.use(express.urlencoded(
  { extended: true }
));
app.use(express.static('public'));

app.locals.siteName = 'BookShelf';
app.locals.year = new Date().getFullYear();

let books = [
  { id: 1, title: '1984',
    author: 'Orwell', year: 1949 },
  { id: 2, title: 'Dune',
    author: 'Herbert', year: 1965 },
];
let nextId = 3;

app.get('/', (req, res) => {
  res.render('pages/home', {
    title: 'Home', books
  });
});

app.get('/books/new', (req, res) => {
  res.render('books/new', {
    title: 'Add Book',
    form: {}, errors: null
  });
});

app.post('/books', (req, res) => {
  const { title, author, year } = req.body;
  if (!title || !author) {
    return res.render('books/new', {
      title: 'Add Book',
      form: req.body,
      errors: { msg: 'All fields required' }
    });
  }
  books.push({
    id: nextId++, title, author,
    year: parseInt(year)
  });
  res.redirect('/');
});

app.listen(3000);