Template Renderer

Overview

o11y-template-renderer is a lightweight Javascript library for loading and rendering templates with dynamic data. It provides functions to parse template strings / files and interpolate data into placeholders supporting also conditional statements like for loop and if. The library reads an input folder, recreates the same file system structure in the output folder, while also resolving placeholders in folder names. Finally, it processes the templates within each file, preserving the original directory structure starting from the input folder.

Use Case

Imagine you have a folder of Grafana dashboards or provisioning files with placeholders like {[{org}]}, {[{env}]}, or {[{team}]}. This script takes care of templating those files using values from a JSON file and renders a new set of files ready for deployment.

Usage

If the package provides a CLI (Command Line Interface), you can execute it directly with npx:

npx o11y-template-renderer --vars=vars.json --in=input_dir --out=output_dir

npx o11y-template-renderer --vars=vars_folder --in=input_dir --out=output_dir

Options

| Option | Description | | -------- | --------------------------------------------------------- | | --vars | JSON data file or folder to inject into the template. | | --in | Input folder with templates or folder structure to render | | --out | Output folder |

Installation

Global Script

If you prefer, you can install the template renderer globally via npm and run it with npx anywhere on your system:

# Install globally
npm install -g @ogcio/o11y-template-renderer

# Run locally from any folder
npx o11y-template-renderer --vars=./templates/dev.json --in=./templates/grafana --out=./grafana
npx o11y-template-renderer --vars=./templates/prod.json --in=./templates/grafana --out=./grafana

This approach allows you to run the template renderer without relying on a Makefile.

Makefile

This is an installation example for a Makefile config. Each name in this example (folder, file, step) is customisable, the template rendering script does not use any fixed names during execution.

Prerequisites

Before running the installation commands, make sure you have the following setup:

1. Templates folder

   • The repository should contain a templates folder with at least two JSON files:
     • dev.json – development environment variables
     • prod.json – production environment variables

2. Grafana configuration (optional but recommended)

   • The templates folder can also contain:
     • grafana/dashboards/ – for your Grafana dashboards
     • grafana/alerting/ – for alert provisioning

3. Node.js

   • Node.js is required only if you plan to run the template renderer.
   • Version: @ogcio/o11y-template-renderer package json.
   • If you don’t have Node.js installed, the template rendering step will fail.

# This rule is used to verify nodejs is installed
# (Optional step if you don't want a safe check on nodejs)
.PHONY: check-nodejs
ensure-o11y-cli:
	@command -v node >/dev/null 2>&1 || { \
		echo "❌ Node.js is not installed. Please install Node >= 20."; \
		exit 1; \
	}
	@echo "✅ Node.js found: $$(node --version)"

# This rule is used to compile templates using the script from the o11y repository.
.PHONY: render-templates
render-templates: ensure-o11y-cli
	@echo "Running template renderer via npx..."
	npx @ogcio/o11y-template-renderer --vars=./templates/dev.json --in=./templates/grafana --out=./grafana
	npx @ogcio/o11y-template-renderer --vars=./templates/prod.json --in=./templates/grafana --out=./grafana
	@echo "Templates compiled successfully."

Examples

simple rendering

npx o11y-template-renderer --vars=vars.json --in=environments/dev --out=environments/rendered

If your structure looks like this:

environments/
├── dev/
│   └── grafana/
│       └── dashboard-{[{org}]}-{[{env}]}.json
├── rendered/

And vars.json contains:

{
  "org": "acme",
  "env": "dev"
}

Then the result will be:

environments/rendered/grafana/dashboard-acme-dev.json

All {[{org}]} and {[{env}]} placeholders in file contents will also be replaced.

conditional template

You can add if statement inside your template and based the condition on:

• vars: json object from env file.
• metadata: object containing file metadata, for example dev.json
  • source file name (dev)
  • extension file extension (json)

env.json

{
  "env": "dev",
  "cluster": "non-prod"
}

template.yaml

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: application-health-{[{env}]}
spec:
{{% if(vars.env == "dev" && vars.cluster == "non-prod") %}}
  folderRef: dev-folder
{{% end-if %}}

output

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: application-health-dev
spec:
  folderRef: dev-folder

for loop in template

The script supports full json with nested objects or arrays.

env.json

{
  "users": [
    { "name": "Alice", "age": 25 },
    { "name": "Bob", "age": 31 }
  ]
}

template.html

<ul>
  {[{#users}]}
  <li>{[{ name }]} — {[{ age }]} years old</li>
  {[{/users}]}
</ul>

output

<ul>
  <li>Alice — 25 years old</li>
  <li>Bob — 31 years old</li>
</ul>

Generated-file notice

Every rendered .yaml/.yml and .json file is marked as generated, so maintainers know to change the source instead of the output. Other file types are written unchanged.

YAML outputs start with a comment header:

# AUTO-GENERATED by @ogcio/o11y-template-renderer. DO NOT EDIT DIRECTLY.
# Template: templates/grafana/base/alerts/application/alerts-{[{env}]}.yaml
# Variables: templates/dev.json
# Edit the source template or variables, then regenerate.

JSON outputs get the same text as the first key of the root object. JSON has no comments, so the notice is stored as data:

{
  "__ogcio_generated": "AUTO-GENERATED by @ogcio/o11y-template-renderer. DO NOT EDIT DIRECTLY. Template: templates/grafana/base/dashboards/application-health/application-health-{[{env}]}.json Variables: templates/dev.json Edit the source template or variables, then regenerate.",
  "annotations": { ... }
}

• Paths are relative to the repository root (the nearest parent folder containing .git, otherwise the working directory). They contain no absolute paths, timestamps or variable values, so rendering unchanged inputs produces identical output.
• The template path keeps its {[{...}]} placeholders, so it points at the file you need to edit.
• A notice already present in a template is replaced, not duplicated.
• Grafana keeps unknown top-level dashboard keys. This was checked against Grafana 13.1 through POST /api/dashboards/db, the endpoint grafana-operator uses. The field is stored as-is, and the operator's drift check sees no difference. Dashboard behaviour does not change.
• JSON files whose root is not an object, or that are not valid JSON after rendering, are written without a notice and the renderer logs a warning.

Changing a generated file

1. Find the source from the notice: edit the Template file for structure/content, or the Variables file for environment-specific values.
2. Regenerate from the repository root, e.g. make render-templates (or the npx @ogcio/o11y-template-renderer ... commands it wraps).
3. Commit the template/variables change together with the regenerated outputs.

Release model

The package is released via release-please.