perf(bundle): lazy-load the nunjucks template engine (#2535)

Closes #2531.

## Summary

The full `nunjucks` templating engine (~226KB) plus `ha-nunjucks`
(~46KB) — roughly **272KB, ~13% of the eager entry chunk** — was
statically imported and downloaded by every card on initial load, even
though templates only apply when a config value contains a `{{ … }}` /
`{% … %}` delimiter. Most cards use no templates and never need the
engine.

This defers the engine behind a dynamic `import('ha-nunjucks/dist')` so
it ships in a separate, on-demand chunk instead of the eager
`card-*.js`.

## Approach

The render path (`TemplateRenderer.renderRecursively`) is **kept
synchronous** — it is called from many synchronous hot paths
(condition/trigger evaluators, picture-elements rendering, actions,
folder matchers), and making it async would be a large, high-risk
refactor of the evaluation core.

Instead:

- **New `src/card-controller/templates/engine.ts`** — a module-level
singleton lazy loader (`loadTemplateEngine()` / `getTemplateEngine()`)
shared across all `TemplateRenderer` instances, plus a
`containsTemplate()` delimiter helper.
- **Delimiter gating** — strings without a delimiter never touch the
engine (the overwhelming majority of renders).
- **Pre-warm at config time** — because every template string originates
in the config, a new mandatory `TEMPLATE_ENGINE` initialization aspect
loads the engine before first render whenever the config contains a
delimiter. This **guarantees no raw `{{ … }}` flash**: content/condition
rendering is blocked until the engine is present for template-using
cards. Cards without templates never load it.

## Result

- nunjucks + ha-nunjucks move out of the eager chunk into a separate
chunk fetched only when a card actually uses templates.
- No change to the synchronous public render API; condition/trigger
evaluation core untouched.

## Tests

- New `engine.ts` loader coverage (concurrent load, cached reuse,
not-loaded fallback).
- The 11 existing test files that render real (delimiter-bearing)
templates declare their dependency explicitly via
`beforeAll(loadTemplateEngine)` — no global/implicit setup hook.
- Full suite green (4764 tests), lint and ts-prune clean, per-file 100%
coverage maintained for the affected directories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c

---
_Generated by [Claude
Code](https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c)_
This commit is contained in:
Dermot Duffy
2026-06-30 17:45:13 -07:00
committed by dermotduffy
parent b33c034810
commit ea251ca988
59 changed files with 1420 additions and 541 deletions
@@ -4,9 +4,11 @@ import { OverridesManager } from '../../../src/card-controller/config/overrides-
import { ConditionStateManager } from '../../../src/condition-trigger/conditions/state-manager';
import type { AdvancedCameraCardConfig } from '../../../src/config/schema/types';
import { AdvancedCameraCardError } from '../../../src/types';
import { createConfig } from '../../test-utils';
import { createConfig, createMockTemplateRenderer } from '../../test-utils';
describe('OverridesManager', () => {
const templateManager = createMockTemplateRenderer();
it('should add overrides', () => {
const config = createConfig({
overrides: [
@@ -25,7 +27,7 @@ describe('OverridesManager', () => {
});
const manager = new OverridesManager(vi.fn());
manager.set(new ConditionStateManager(), config.overrides);
manager.set(new ConditionStateManager(), templateManager, config.overrides);
expect(manager.hasOverrides()).toBe(true);
});
@@ -49,11 +51,11 @@ describe('OverridesManager', () => {
const stateManager = new ConditionStateManager();
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
expect(manager.getConfig(config).menu?.style).toBe('hidden');
manager.set(stateManager, []);
manager.set(stateManager, templateManager, []);
stateManager.setState({ fullscreen: true });
expect(manager.getConfig(config).menu?.style).toBe('hidden');
@@ -79,7 +81,7 @@ describe('OverridesManager', () => {
});
const manager = new OverridesManager(vi.fn());
manager.set(new ConditionStateManager(), config.overrides);
manager.set(new ConditionStateManager(), templateManager, config.overrides);
expect(manager.getConfig(config)).toBe(config);
});
@@ -104,7 +106,7 @@ describe('OverridesManager', () => {
const callback = vi.fn();
const stateManager = new ConditionStateManager();
const manager = new OverridesManager(callback);
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
expect(manager.getConfig(config).menu?.style).toBe('hidden');
@@ -139,7 +141,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -174,7 +176,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -205,7 +207,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -240,7 +242,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -276,7 +278,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -310,7 +312,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
const overriddenConfig = manager.getConfig(config);
@@ -341,7 +343,7 @@ describe('OverridesManager', () => {
stateManager.setState({ fullscreen: true });
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
let thrown: unknown = null;
try {
@@ -442,7 +444,7 @@ describe('OverridesManager', () => {
const stateManager = new ConditionStateManager();
const manager = new OverridesManager(vi.fn());
manager.set(stateManager, config.overrides);
manager.set(stateManager, templateManager, config.overrides);
expect(manager.getConfig(config).live.controls.thumbnails.mode).toBe('right');