Nunchucks Documentation

Install CLI (Recommended)

Most users should use the CLI first, then add language wrappers only where needed.

# Build local CLI binary
cd go
go build -o ../bin/nunchucks ./cmd/nunchucks

# Run
../bin/nunchucks help
../bin/nunchucks render -views ./views -template index.njk -data '{"title":"Hello"}'

# Or install with Go
go install github.com/SamuelDBines/nunjucks/go/cmd/nunchucks@latest

Direct binary downloads (when published): GitHub Releases.

Pick A Language

Use the selector to view wrapper/integration patterns from each runtime. CLI usage above remains the primary path.

env := nunchucks.Configure(nunchucks.ConfigOptions{Path: "views"})
out, err := env.Render("index.njk", map[string]any{
  "user": map[string]any{"name": "sam"},
})
if err != nil {
  panic(err)
}
fmt.Println(out)

# CLI
go run ./cmd/nunchucks help
go run ./cmd/nunchucks render -views ./views -template index.njk -data '{"title":"Hello"}'
go run ./cmd/nunchucks precompile -views ./views -out ./public -data '{"title":"Hello"}'

# WASM build
cd go
GOOS=js GOARCH=wasm go build -o wasm/nunchucks.wasm ./cmd/nunchucks-wasm
cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" wasm/wasm_exec.js

import { loadNunchucksWasm } from "@samuelbines/nunchucks";

const nc = await loadNunchucksWasm({
  wasmURL: "/node_modules/@samuelbines/nunchucks/go/wasm/nunchucks.wasm",
  goURL: "/node_modules/@samuelbines/nunchucks/go/wasm/wasm_exec.js",
});

const html = nc.renderFromMap({
  template: "index.njk",
  files: { "index.njk": "Hello {{ user.name }}" },
  context: { user: { name: "sam" } },
});

import { loadNunchucksWasm } from "@samuelbines/nunchucks";

const nc = await loadNunchucksWasm({
  wasmURL: "/node_modules/@samuelbines/nunchucks/go/wasm/nunchucks.wasm",
  goURL: "/node_modules/@samuelbines/nunchucks/go/wasm/wasm_exec.js",
});

const out = nc.renderFromMap({
  template: "index.njk",
  files: {
    "index.njk": "Hello {{ user.name }}",
  },
  context: { user: { name: "sam" } },
});

# Python wrapper pattern (current): call nunchucks CLI
import json
import subprocess

cmd = [
  "nunchucks", "render",
  "-views", "./views",
  "-template", "index.njk",
  "-data", json.dumps({"user": {"name": "sam"}}),
]
out = subprocess.check_output(cmd, text=True)
print(out)

// Dart wrapper pattern (current): call nunchucks CLI
import 'dart:convert';
import 'dart:io';

final result = await Process.run('nunchucks', [
  'render',
  '-views', './views',
  '-template', 'index.njk',
  '-data', jsonEncode({'user': {'name': 'sam'}}),
]);
print(result.stdout);

Go CLI/runtime is the source path. JS/TS use the Go WASM bridge; Python/Dart can use the CLI bridge today.

Quick Start

Package: github.com/SamuelDBines/nunjucks/go

env := nunchucks.Configure(nunchucks.ConfigOptions{Path: "views"})
out, err := env.Render("index.njk", map[string]any{
    "title": "Nunchucks",
    "items": []any{"alpha", "beta"},
})
if err != nil {
    panic(err)
}
fmt.Println(out)

CLI

go run ./cmd/nunchucks help
go run ./cmd/nunchucks render -views ./views -template index.njk -data '{"title":"Hello"}'
go run ./cmd/nunchucks precompile -views ./views -out ./public -data '{"title":"Hello"}'

Examples

cd go
go run ./examples/basic
go run ./examples/advanced

Detailed Example A: Template Composition

# views/layout.njk
<h1>{% block title %}Title{% endblock %}</h1>
<main>{% block body %}{% endblock %}</main>

# views/macros.njk
{% macro badge(text) %}<span class="badge">{{ text | upper }}</span>{% endmacro %}

# views/home.njk
{% extends "layout.njk" %}
{% import "macros.njk" as ui %}
{% block title %}Users{% endblock %}
{% block body %}
  {% for u in users %}
    {{ ui.badge(u.name) }}
  {% endfor %}
{% endblock %}

env := nunchucks.Configure(nunchucks.ConfigOptions{Path: "views"})
out, err := env.Render("home.njk", map[string]any{
  "users": []any{
    map[string]any{"name": "sam"},
    map[string]any{"name": "kai"},
  },
})
if err != nil { panic(err) }

Detailed Example B: Filter + Function Parity

{% set active = users | selectattr("active") %}
Active={{ active | length }}

{% for grp in users | groupby("role", "none") %}
{{ grp.grouper }}={{ grp.list | length }}
{% endfor %}

BestScoreKey={{ scores | dictsort("value", false, true) | first | first }}
Intervals={{ range(0, 10, 3) | join(",") }}

out, err := env.Render("report.njk", map[string]any{
  "users": []any{
    map[string]any{"name":"A","active":true,"role":"Dev"},
    map[string]any{"name":"B","active":false,"role":"ops"},
    map[string]any{"name":"C","active":true,"role":"dev"},
  },
  "scores": map[string]any{"x": 4, "y": 7, "z": 2},
})

WASM Target

The Go core can be compiled to WebAssembly and consumed from JS runtimes.

cd go
GOOS=js GOARCH=wasm go build -o wasm/nunchucks.wasm ./cmd/nunchucks-wasm
cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" wasm/wasm_exec.js

Then load with go/wasm/loader.js and call:

• renderFromMap({ template, files, context })
• renderString({ source, context })

Client Runtime

Nunchucks now supports a first client-runtime layer in the Go engine. {% client %}...{% endclient %} compiles to browser module scripts, {% fetch %} compiles to async fetch calls, and {% state %} bootstraps state under window.__nunchucks.state.

<button onClick={{ app.pressed = true }}>Press</button>
{% client %}
{% state app | { pressed: false } | %}
{% fetch | '/api/users/' + userID | as user | %}
console.log(user.name)
{% endclient %}

App Builder Workspace

The local app builder now stores files in browser IndexedDB rather than writing to shared server files by default. This makes per-user sessions isolated and safer for multi-user usage.

Controls available in the app builder: Reset, Import, Export, and Download output.

Tags

Current Go runtime support:

• if, for, set
• extends, block, include
• macro, import ... as, call
• raw, verbatim, filter ... endfilter

{% import "macros.njk" as ui %}
{% set name = "sam" %}
{% if name %}{{ ui.badge(name) }}{% endif %}

Filters

Current Go filters include:

• abs, batch, capitalize, center, default
• dictsort, dump, escape, first, float, forceescape
• groupby, indent, int, join, last, length, list
• lower, nl2br, random, reject, rejectattr, replace
• reverse, round, safe, select, selectattr, slice, sort
• string, striptags, sum, title, trim, truncate, upper
• urlencode, urlize, wordcount

{{ "NUNCHUCKS" | lower }}
{{ "nunchucks" | upper }}
{% filter upper %}hello {{ user.name }}{% endfilter %}

Note: behavior is close to Nunjucks/Jinja for most filters, with a few edge cases still being tightened.

Deep Example 1: Macros + Layout + Call Blocks

Use this when you want reusable UI components and nested content.

# base.njk
<!doctype html>
<html>
  <body>
    <header>{% block header %}Default Header{% endblock %}</header>
    <main>{% block content %}{% endblock %}</main>
  </body>
</html>

# macros.njk
{% macro panel(kind="info") %}
<section class="panel panel-{{ kind }}">
  {{ caller() }}
</section>
{% endmacro %}

# page.njk
{% extends "base.njk" %}
{% import "macros.njk" as ui %}
{% block header %}Account Overview{% endblock %}
{% block content %}
  {% call ui.panel("success") %}
    Hello {{ user.name | title }}
  {% endcall %}
{% endblock %}

env := nunchucks.Configure(nunchucks.ConfigOptions{Path: "views"})
out, err := env.Render("page.njk", map[string]any{
  "user": map[string]any{"name": "samuel"},
})
if err != nil { panic(err) }
fmt.Println(out)

Deep Example 2: Data Shaping (groupby + dictsort + selectattr + range)

Use this when rendering dashboards, reports, and config summaries.

{# users grouped by role (case-insensitive by default) #}
{% for grp in users | groupby("role", "none") %}
Role={{ grp.grouper }} count={{ grp.list | length }}
{% endfor %}

{# active users only #}
Active={{ users | selectattr("active") | length }}

{# reverse sort map by value #}
TopKey={{ scores | dictsort("value", false, true) | first | first }}

{# deterministic ranges from builtin function #}
Steps={{ range(1, 8, 2) | join(",") }}

out, err := env.Render("report.njk", map[string]any{
  "users": []any{
    map[string]any{"name":"Zed","role":"Dev","active":true},
    map[string]any{"name":"Amy","role":"ops","active":false},
    map[string]any{"name":"Bob","role":"dev","active":true},
  },
  "scores": map[string]any{"alpha": 92, "beta": 87, "gamma": 95},
})