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>

Release model

The package is released via release-please.