feat: migrate Phase 2 SSR - replace DustJS/jQuery/Sammy with Nunjucks/Vanilla JS

[mikaello]

Phase 2: Server-Side Rendering Migration

Replaces client-side DustJS rendering + jQuery + Sammy.js with server-side Nunjucks rendering + Vanilla JS.

Changes

New files:

• src/schema_parser.js — server-side port of public/js/schema.js + buildAvroDocContext()
• src/top_level.njk — top-level Nunjucks template (replaces src/top_level.dust)
• templates/*.njk — Nunjucks templates for all schema views

Modified files:

• src/static_content.js — fully rewritten using Nunjucks SSR; all sections pre-rendered server-side
• public/js/avrodoc.js — replaced with Vanilla JS (hash routing, popovers, search)
• app.js — loads JSON schemata at startup, removed dust-templates route
• eslint.config.js — removed jQuery/$ globals
• src/avrodoc.test.js — updated assertion to check for SSR output marker (data-route)

Removed: public/js/schema.js, all vendor DustJS/jQuery/Sammy/markdown files, templates/*.dust, dustjs npm dependencies

Architecture

All HTML is rendered server-side. The browser receives <section data-route="..." elements and a <script id="popover-data" JSON blob. Vanilla JS handles hash routing, Bootstrap popovers, and sidebar search.

[github-actions]

Avrodoc Preview 🔍

A live preview of the generated documentation is available at:
👉 https://mikaello.github.io/avrodoc-plus/pr-preview/pr-361/

This preview is built from the schemata/ directory and updates on every push to this PR.

[mikaello]

Performance note: scaling with large schema sets

The SSR approach renders all content upfront. Per-type cost is ~3.8 KB (2.6 KB section HTML + 1.2 KB popover JSON). At 1000 types this is ~4 MB total HTML; at 5000 types ~19 MB. The old lazy approach (client-side dust rendering) also scaled poorly (blocking JS parse + large embedded JSON), but the trade-off shifts at large scale.

Two concrete optimizations for a future iteration

1. Eliminate popover data duplication (~50% size reduction per type)

The popover JSON (in <script id="popover-data" type="application/json">) contains named_type_details HTML that is already present in the hidden <section> elements. Instead, popovers can read their content directly from the DOM:

// In setupPopovers(), replace JSON lookup with DOM lookup:
var section = findSection('#/schema/' + encodeURIComponent(filename) + '/' + encodeURIComponent(qualifiedName));
var content = section ? section.innerHTML : null;

Remove buildPopoverData() in static_content.js, and the popover-only templates (popover_title.njk, named_type_details.njk). This cuts per-type cost from ~3.8 KB to ~2.6 KB and eliminates double-rendering of named_type_details at server startup.

2. Lazy section rendering for server mode

In app.js (server mode, not CLI inline mode), pre-render only the sidebar and the #/ default section. Add an endpoint GET /section/:filename/:qualifiedName that renders and returns a single section on demand. The client fetches and injects it on first navigation, caching it in the DOM. This keeps initial HTML small (~50 KB) and scales to arbitrarily large schema sets without changing the CLI inline behaviour.

[mikaello]

I tested this rewrite against the avrodoc-plus-demo stress-test repo (497 schemas covering full Avro 1.12.1 spec). See the test PR here: mikaello/avrodoc-plus-demo#2

Result

The build fails with the same cross-file reference error (#362):

Unknown type name "com.example.enums.LogLevel" at logLevel

What changed vs. the original

The SSR rewrite improves the failure mode — it's now a hard build-time crash instead of a silent browser console error. That's a meaningful step forward.

However, schema_parser.js → buildAvroDocContext uses the same eager type resolution as the original public/js/schema.js. Schemas are processed in alphabetical filename order; if schema A (complex/) references a type defined in schema B (enums/), and B sorts after A, the lookup fails.

Suggested fix

A first-pass pre-registration step in buildAvroDocContext before the main parse loop would fix it:

// Pass 1: register all top-level named type names into shared_types
// (without resolving field types)
for (const { filename, json } of input_schemata) {
  preRegisterTopLevelTypes(json, shared_types);
}

// Pass 2: full parse (existing loop) — cross-file refs now resolvable
for (const { filename, json } of input_schemata) {
  // ... current parseAvroSchema call
}

preRegisterTopLevelTypes would only need to walk the top-level schema and nested types arrays (for protocols) to collect record/enum/fixed fullnames — no field resolution needed.