@gavinrigs/decap-nunjucks-preview
v1.0.2
Published
Renders Decap CMS previews with the site's own Nunjucks templates, filters and stylesheets.
Readme
@gavinrigs/decap-nunjucks-preview
Renders the Decap CMS preview pane with the site's own Nunjucks templates, filters, globals and stylesheets, so the editor sees the real page rather than a hand-maintained React approximation.
Registering
import CMS from "decap-cms-app";
import { register } from "@gavinrigs/decap-nunjucks-preview";
register(CMS, {
collections: {
posts: "reactive",
templates: "dynamic",
},
styles: ["/css/main.css"],
filters: { readableDate, slug },
globals: { relation2Resolve },
wrapper: {
bodyClass: "bg-site min-h-screen flex flex-col",
mainClass: "flex-1",
fonts: ["https://fonts.googleapis.com/css2?family=Lora&display=swap"],
},
});Preview types
| Type | Behaviour |
| --- | --- |
| reactive | Renders the Nunjucks template stored in the entry's template field (fetched by a resolved widget such as hiddenfetch), against the entry's own data plus any resolved data. |
| dynamic | Renders the template and test_data code fields stored directly on the entry — used for editing templates themselves. |
Options
| Option | Default | Purpose |
| --- | --- | --- |
| collections | {} | Collection name → preview type. |
| styles | [] | Stylesheet URLs injected into the preview pane. |
| filters | {} | Nunjucks filters. A luxon-backed date filter is always registered. |
| globals | {} | Nunjucks globals. |
| componentTemplates | {} | Inline template sources so {% include %} resolves in the browser, which has no filesystem. |
| wrapper | {} | Page chrome reproduced around the output: bodyClass, mainClass, mainId, headHtml, fonts. |
| resolvedWidgets | ["relation2","hiddenfetch"] | Widget names whose data comes from an entry-data provider. |
| templateField | "cms_template" | Field holding the template for reactive collections. |
| uploadFolders | ["/images","/images/uploads"] | Media folders indexed when previewing unsaved uploads. |
| CMS | bundled decap-cms-app | Decap instance to register against. |
wrapper
Templates normally {% extends %} a base layout that the preview cannot load,
so the extends tag is stripped and this wrapper stands in for it. Supply the
same classes the site's <body> and <main> use so the site's CSS matches.
fonts is expanded into preconnect hints plus stylesheet links; anything more
specific goes in headHtml.
Behaviour worth knowing
- Images not yet saved are rewritten to blob URLs before injection, so the browser never requests a path that does not exist yet.
- Cross-context updates: the preview runs in its own iframe JS context, so resolved data arrives over the core message bus and is cached locally; the same-context path is preferred when available.
- Lucide icons in rendered output are hydrated after each render.
Security assumption
Rendered template output is injected with dangerouslySetInnerHTML, because the
whole point is to show the real markup a template produces — escaping it would
defeat that. This is safe only under the assumption that both the templates and
the entry data come from authenticated CMS editors you already trust with the
content of the site. Do not point this preview at templates or data from an
untrusted source; there is no sanitisation step.
Dependencies
@gavinrigs/decap-plugin-core- Peer:
decap-cms-app,nunjucks,luxon,lucide,react
Works without any widget plugin installed; it simply has no resolved data to merge.