Integrate a custom engine
A rendering package does not expose Express's expected integration property.
Express.js · Module
app.engine
Registers a template-engine callback for a file extension. Use it for custom engines or to map an alternate extension to an engine.
How it works
app.engine registers a rendering callback for a file extension. The callback receives the view file path, rendering options, and a completion callback; it must return either an error or rendered output, after which Express can use the engine for matching views.
Syntax
app.engine(ext, callback)Parameters
| Name | Type | Description |
|---|---|---|
ext | String | File extension for which the template engine is registered, such as pug or html. |
callback | Function | Template-engine function used to render files with the specified extension. |
Returns
Application
Key points
- The first argument names the extension whose views the renderer will handle, such as pug or html.
- The second argument is the rendering function for files matching the registered extension.
- Calling app.engine associates the callback with the extension in the application.
- The method supports engines without Express's expected __express integration.
- It can map a custom or alternate file extension to an existing rendering engine.
Common mistakes
- Express automatically loads an engine based on its extension, so use app.engine when the engine does not expose the expected integration hook or when mapping a different extension.
- Use app.engine for template engines that lack the __express integration property.
Example: Register a custom template engine
const express = require('express');
const fs = require('fs');
const app = express();
app.engine('ntl', (filePath, options, callback) => {
fs.readFile(filePath, (err, content) => {
if (err) return callback(err);
const rendered = content.toString()
.replace('#title#', `<title>${options.title}</title>`)
.replace('#message#', `<h1>${options.message}</h1>`);
callback(null, rendered);
});
});
app.set('views', './views');
app.set('view engine', 'ntl');
app.get('/', (req, res) => res.render('index', { title: 'Home', message: 'Hello' }));
app.listen(3000);Registers a minimal file-based .ntl engine, configures it as the view engine, and renders a view.
When to use it
Map an alternate extension
Templates use a file suffix different from the engine's default suffix.
Define a lightweight renderer
An application needs a small project-specific renderer.
Interview questions
QWhat does app.engine do?
app.engine(ext, callback) registers the callback as the renderer for the supplied extension and returns the application object. The extension identifies the view files handled by that renderer.
Follow-up: How would you support an engine under a different extension? Register the desired extension with app.engine and provide the engine's rendering callback.
QWhat arguments does a custom engine callback use?
The callback is the template-engine function used to render files with the registered extension. A custom callback convention receives the file location, options object, and completion callback, then reports an error or rendered text.
Follow-up: What should the completion callback receive on success? It should receive no error and the rendered output.
QWhen is app.engine especially useful?
Express normally loads a template engine according to the view file extension. app.engine is appropriate when the engine does not provide __express or when an extension must be mapped to another engine.
Follow-up: What other settings are needed for a complete custom-engine setup? Configure the views directory and set the view engine extension before rendering views.
Related
app.setapp.renderres.renderview engineviews