Hello, <%= name %>!
\n \n\n```\n\n```js\n// index.js:\nconst fastify = require(\"fastify\")()\nconst fastifyView = require(\"@fastify/view\")\n\nfastify.register(fastifyView, {\n engine: {\n ejs: require(\"ejs\")\n }\n})\n\n// synchronous handler:\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"index.ejs\", { name: \"User\" });\n})\n\n// asynchronous handler:\nfastify.get(\"/\", async (req, reply) => {\n return reply.viewAsync(\"index.ejs\", { name: \"User\" });\n})\n\nfastify.listen({ port: 3000 }, (err) => {\n if (err) throw err;\n console.log(`server listening on ${fastify.server.address().port}`);\n})\n```\n\n## Configuration\n\n### Options\n\n| Option | Description | Default |\n| ---------------------- | ----------- | ------- |\n| `engine` | **Required**. The template engine object - pass in the return value of `require('<%= text %>
\n```\n\n```js\n// index.js:\nfastify.register(fastifyView, {\n engine: { ejs },\n layout: \"layout.ejs\"\n})\n\nfastify.get('/', (req, reply) => {\n const data = { text: \"Hello!\"}\n reply.view('template.ejs', data)\n})\n```\n\n### Providing a layout on render\n**Please note:** Global layouts and providing layouts on render are mutually exclusive. They can not be mixed.\n\n```js\nfastify.get('/', (req, reply) => {\n const data = { text: \"Hello!\"}\n reply.view('template.ejs', data, { layout: 'layout.ejs' })\n})\n```\n\n## Setting request-global variables\nSometimes, several templates should have access to the same request-specific variables. E.g. when setting the current username.\n\nIf you want to provide data, which will be depended on by a request and available in all views, you have to add property `locals` to `reply` object, like in the example below:\n\n```js\nfastify.addHook(\"preHandler\", function (request, reply, done) {\n reply.locals = {\n text: getTextFromRequest(request), // it will be available in all views\n };\n\n done();\n});\n```\n\nProperties from `reply.locals` will override those from `defaultContext`, but not from `data` parameter provided to `reply.view(template, data)` function.\n\n## Rendering the template into a variable\nThe `fastify` object is decorated the same way as `reply` and allows you to just render a view into a variable (without request-global variables) instead of sending the result back to the browser:\n\n```js\n// Promise based, using async/await\nconst html = await fastify.view(\"/templates/index.ejs\", { text: \"text\" });\n\n// Callback based\nfastify.view(\"/templates/index.ejs\", { text: \"text\" }, (err, html) => {\n // Handle error\n // Do something with `html`\n});\n```\n\nIf called within a request hook and you need request-global variables, see [Migrating from view to viewAsync](#migrating-from-view-to-viewAsync).\n\n\n## Registering multiple engines\n\nRegistering multiple engines with different configurations is supported. They are distinguished via their `propertyName`:\n\n```js\nfastify.register(require(\"@fastify/view\"), {\n engine: { ejs: ejs },\n layout: \"./templates/layout-mobile.ejs\",\n propertyName: \"mobile\",\n});\n\nfastify.register(require(\"@fastify/view\"), {\n engine: { ejs: ejs },\n layout: \"./templates/layout-desktop.ejs\",\n propertyName: \"desktop\",\n});\n\nfastify.get(\"/mobile\", (req, reply) => {\n // Render using the `mobile` render function\n return reply.mobile(\"/templates/index.ejs\", { text: \"text\" });\n});\n\nfastify.get(\"/desktop\", (req, reply) => {\n // Render using the `desktop` render function\n return reply.desktop(\"/templates/index.ejs\", { text: \"text\" });\n});\n```\n\n## Rendering a template from a string (\"raw\" template)\n\nThe `reply.view({ raw })` option allows you to render a template from a string instead of a file. This is useful when you want to render a template that is not stored in a file, or when you want to use a template that is generated dynamically.\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.mustache', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\nNote that by using the `raw` option, you are considering the template as trusted - `@fastify/view` does not perform any\nvalidation on the template content.\n\n__DO NOT USE `raw` with untrusted content, or you will make yourself vulnerable to Remote Code Execution (RCE) attacks.__\n\n## Minifying HTML on render\n\nTo utilize [`html-minifier-terser`](https://www.npmjs.com/package/html-minifier-terser) in the rendering process, you can add the option `useHtmlMinifier` with a reference to `html-minifier-terser`,\nand the optional `htmlMinifierOptions` option is used to specify the `html-minifier-terser` options:\n\n```js\n// get a reference to html-minifier-terser\nconst minifier = require('html-minifier-terser')\n// optionally defined the html-minifier-terser options\nconst minifierOpts = {\n removeComments: true,\n removeCommentsFromCDATA: true,\n collapseWhitespace: true,\n collapseBooleanAttributes: true,\n removeAttributeQuotes: true,\n removeEmptyAttributes: true\n}\n// in template engine options configure the use of html-minifier\n options: {\n useHtmlMinifier: minifier,\n htmlMinifierOptions: minifierOpts\n }\n```\n\nTo exclude paths from minification, you can add the option `pathsToExcludeHtmlMinifier` with a list of paths:\n```js\n// get a reference to html-minifier-terser\nconst minifier = require('html-minifier-terser')\n// in options configure the use of html-minifier-terser and set paths to exclude from minification\nconst options = {\n useHtmlMinifier: minifier,\n pathsToExcludeHtmlMinifier: ['/test']\n}\n\nfastify.register(require(\"@fastify/view\"), {\n engine: {\n ejs: require('ejs')\n },\n options\n});\n\n// This path is excluded from minification\nfastify.get(\"/test\", (req, reply) => {\n reply.view(\"./template/index.ejs\", { text: \"text\" });\n});\n\n```\n\n\n\n## Engine-specific settings\n\n\n\n### Mustache\n\nTo use partials in mustache you will need to pass the names and paths in the options parameter:\n\n```js\n options: {\n partials: {\n header: 'header.mustache',\n footer: 'footer.mustache'\n }\n }\n```\n\n```js\nfastify.get('/', (req, reply) => {\n reply.view('./templates/index.mustache', data)\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.mustache', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n const render = mustache.render.bind(mustache, file)\n reply.view(render, data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.mustache', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### Handlebars\n\nTo use partials in handlebars you will need to pass the names and paths in the options parameter:\n\n```js\n options: {\n partials: {\n header: 'header.hbs',\n footer: 'footer.hbs'\n }\n }\n```\n\nYou can specify [compile options](https://handlebarsjs.com/api-reference/compilation.html#handlebars-compile-template-options) as well:\n\n```js\n options: {\n compileOptions: {\n preventIndent: true\n }\n }\n```\n\nTo access `defaultContext` and `reply.locals` as [`@data` variables](https://handlebarsjs.com/api-reference/data-variables.html):\n\n```js\n options: {\n useDataVariables: true\n }\n```\n\nTo use layouts in handlebars you will need to pass the `layout` parameter:\n\n```js\nfastify.register(require(\"@fastify/view\"), {\n engine: {\n handlebars: require(\"handlebars\"),\n },\n layout: \"./templates/layout.hbs\",\n});\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"./templates/index.hbs\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.hbs', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n const render = handlebars.compile(file)\n reply.view(render, data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.hbs', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### Nunjucks\n\nYou can load templates from multiple paths when using the nunjucks engine:\n\n```js\nfastify.register(require(\"@fastify/view\"), {\n engine: {\n nunjucks: require(\"nunjucks\"),\n },\n templates: [\n \"node_modules/shared-components\",\n \"views\",\n ],\n});\n```\n\nTo configure nunjucks environment after initialization, you can pass callback function to options:\n\n```js\noptions: {\n onConfigure: (env) => {\n // do whatever you want on nunjucks env\n };\n}\n```\n\n```js\nfastify.get('/', (req, reply) => {\n reply.view('./templates/index.njk', data)\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.njk', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n const render = nunjucks.compile(file)\n reply.view(render, data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.njk', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### Liquid\n\nTo configure liquid you need to pass the engine instance as engine option:\n\n```js\nconst { Liquid } = require(\"liquidjs\");\nconst path = require('node:path');\n\nconst engine = new Liquid({\n root: path.join(__dirname, \"templates\"),\n extname: \".liquid\",\n});\n\nfastify.register(require(\"@fastify/view\"), {\n engine: {\n liquid: engine,\n },\n});\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"./templates/index.liquid\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.liquid', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n const render = engine.renderFile.bind(engine, './templates/index.liquid')\n reply.view(render, data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.liquid', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### doT\n\nWhen using [doT](https://github.com/olado/doT) the plugin compiles all templates when the application starts, this way all `.def` files are loaded and\nboth `.jst` and `.dot` files are loaded as in-memory functions.\nThis behavior is recommended by the doT team [here](https://github.com/olado/doT#security-considerations).\nTo make it possible it is necessary to provide a `root` or `templates` option with the path to the template directory.\n\n```js\nfastify.register(require(\"@fastify/view\"), {\n engine: {\n dot: require(\"dot\"),\n },\n root: \"templates\",\n options: {\n destination: \"dot-compiled\", // path where compiled .jst files are placed (default = 'out')\n },\n});\n\nfastify.get(\"/\", (req, reply) => {\n // this works both for .jst and .dot files\n reply.view(\"index\", { text: \"text\" });\n});\n```\n\n```js\nconst d = dot.process({ path: 'templates', destination: 'out' })\nfastify.get('/', (req, reply) => {\n reply.view(d.index, data)\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n reply.view({ raw: readFileSync('./templates/index.dot'), imports: { def: readFileSync('./templates/index.def') } }, data)\n})\n```\n\n### eta\n\n```js\nconst { Eta } = require('eta')\nlet eta = new Eta()\nfastify.register(pointOfView, {\n engine: {\n eta\n },\n templates: 'templates'\n})\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"index.eta\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.eta', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view(eta.compile(file), data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.eta', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### ejs\n\n```js\nconst ejs = require('ejs')\nfastify.register(pointOfView, {\n engine: {\n ejs\n },\n templates: 'templates'\n})\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"index.ejs\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.ejs', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view(ejs.compile(file), data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.ejs', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### pug\n\n```js\nconst pug = require('pug')\nfastify.register(pointOfView, {\n engine: {\n pug\n }\n})\n\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"index.pug\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.pug', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view(pug.compile(file), data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.pug', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### twig\n\n```js\nconst twig = require('twig')\nfastify.register(pointOfView, {\n engine: {\n twig\n }\n})\n\n\nfastify.get(\"/\", (req, reply) => {\n reply.view(\"index.twig\", { text: \"text\" });\n});\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.twig', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view(twig.twig({ data: file }), data)\n }\n })\n})\n```\n\n```js\nfastify.get('/', (req, reply) => {\n fs.readFile('./templates/index.twig', 'utf8', (err, file) => {\n if (err) {\n reply.send(err)\n } else {\n reply.view({ raw: file }, data)\n }\n })\n})\n```\n\n### Edge\n\n```js\nconst { Edge } = require('edge.js')\nconst { join } = require('node:path')\n\nconst engine = new Edge()\nengine.mount(join(__dirname, '..', 'templates'))\n\nfastify.register(require('../index'), {\n engine: {\n edge: engine\n }\n})\n\nfastify.get('/', (_req, reply) => {\n reply.view('index.edge', data)\n})\n```\n\n### Squirrelly\n\n```js\nconst Sqrl = require('squirrelly')\n\nfastify.register(require('@fastify/view'), {\n engine: {\n squirrelly: Sqrl\n },\n templates: 'templates'\n})\n\nfastify.get('/', (_req, reply) => {\n reply.view('index.squirrelly', { text: 'Hello World!' })\n})\n```\n\n\n\n## Miscellaneous\n\n### Using @fastify/view as a dependency in a fastify-plugin\n\nTo require `@fastify/view` as a dependency to a [fastify-plugin](https://github.com/fastify/fastify-plugin), add the name `@fastify/view` to the dependencies array in the [plugin's opts](https://github.com/fastify/fastify-plugin#dependencies).\n\n```js\nfastify.register(myViewRendererPlugin, {\n dependencies: [\"@fastify/view\"],\n});\n```\n\n### Forcing a cache-flush\n\nTo forcefully clear the cache when in production mode, call the `view.clearCache()` function.\n\n```js\nfastify.view.clearCache();\n```\n\n\n\n### Migrating from `view` to `viewAsync`\n\nThe behavior of `reply.view` is to immediately send the HTML response as soon as rendering is completed, or immediately send a 500 response with error if encountered, short-circuiting fastify's error handling hooks, whereas `reply.viewAsync` returns a promise that either resolves to the rendered HTML, or rejects on any errors. `fastify.view` has no mechanism for providing request-global variables, if needed. `reply.viewAsync` can be used in both sync and async handlers.\n\n#### Sync handler\nPreviously:\n```js\nfastify.get('/', (req, reply) => {\n reply.view('index.ejs', { text: 'text' })\n})\n```\nNow:\n```js\nfastify.get('/', (req, reply) => {\n return reply.viewAsync('index.ejs', { text: 'text' })\n})\n```\n#### Async handler\nPreviously:\n```js\n// This is an async function\nfastify.get(\"/\", async (req, reply) => {\n const data = await something();\n reply.view(\"/templates/index.ejs\", { data });\n return\n})\n```\n\nNow:\n```js\n// This is an async function\nfastify.get(\"/\", async (req, reply) => {\n const data = await something();\n return reply.viewAsync(\"/templates/index.ejs\", { data });\n})\n```\n#### fastify.view (when called inside a route hook)\nPreviously:\n```js\n// Promise based, using async/await\nfastify.get(\"/\", async (req, reply) => {\n const html = await fastify.view(\"/templates/index.ejs\", { text: \"text\" });\n return html\n})\n```\n```js\n// Callback based\nfastify.get(\"/\", (req, reply) => {\n fastify.view(\"/templates/index.ejs\", { text: \"text\" }, (err, html) => {\n if(err) {\n reply.send(err)\n }\n else {\n reply.type(\"application/html\").send(html)\n }\n });\n})\n```\nNow:\n```js\n// Promise based, using async/await\nfastify.get(\"/\", (req, reply) => {\n const html = await fastify.viewAsync(\"/templates/index.ejs\", { text: \"text\" });\n return html\n})\n```\n```js\nfastify.get(\"/\", (req, reply) => {\n fastify.viewAsync(\"/templates/index.ejs\", { text: \"text\" })\n .then((html) => reply.type(\"application/html\").send(html))\n .catch((err) => reply.send(err))\n });\n})\n```\n\n## Note\n\nBy default, views are served with the mime type `text/html`, with the charset specified in options. You can specify a different `Content-Type` header using `reply.type`.\n\n## Acknowledgments\n\nThis project is kindly sponsored by:\n\n- [nearForm](https://nearform.com)\n- [LetzDoIt](https://www.letzdoitapp.com/)\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","readmeFilename":"README.md"}