flan/advanced-camera-card
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
tests/card-controller/templates/index.test.ts
+148 -53
View File
@@ -1,35 +1,117 @@
import { describe, expect, it } from 'vitest';
import { describe, expect, it, vi } from 'vitest';
import { TemplateRenderer } from '../../../src/card-controller/templates/index';
import { TemplateManager } from '../../../src/card-controller/templates/index';
import { createConfig, createHASS, createStateEntity } from '../../test-utils';
describe('TemplateRenderer', () => {
describe('TemplateManager', () => {
describe('loadRenderer', () => {
it('should render a template raw before the engine is loaded', () => {
const manager = new TemplateManager();
const result = manager.renderRecursively(createHASS(), '{{ acc.camera }}', {
conditionState: { camera: 'camera.office' },
});
expect(result).toBe('{{ acc.camera }}');
});
it('should render a template after the engine is loaded', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const result = manager.renderRecursively(createHASS(), '{{ acc.camera }}', {
conditionState: { camera: 'camera.office' },
});
expect(result).toBe('camera.office');
});
it('should be idempotent across repeat loads', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
await manager.loadRenderer();
const result = manager.renderRecursively(createHASS(), '{{ acc.camera }}', {
conditionState: { camera: 'camera.office' },
});
expect(result).toBe('camera.office');
});
it('should pass a non-template string through unchanged before loading', () => {
const manager = new TemplateManager();
expect(manager.renderRecursively(createHASS(), 'hello world')).toBe('hello world');
});
it('should prime the renderer on demand when a template is rendered unloaded', () => {
const manager = new TemplateManager();
const loadRenderer = vi.spyOn(manager, 'loadRenderer').mockResolvedValue();
manager.renderRecursively(createHASS(), '{{ acc.camera }}');
expect(loadRenderer).toBeCalled();
});
it('should swallow a load failure when priming on an unloaded render', () => {
const manager = new TemplateManager();
vi.spyOn(manager, 'loadRenderer').mockRejectedValue(new Error('load failed'));
expect(() =>
manager.renderRecursively(createHASS(), '{{ acc.camera }}'),
).not.toThrow();
});
});
describe('isLoaded', () => {
it('should report false before loading and true after', async () => {
const manager = new TemplateManager();
expect(manager.isLoaded()).toBe(false);
await manager.loadRenderer();
expect(manager.isLoaded()).toBe(true);
});
});
describe('dataContainsTemplate', () => {
it.each([
['an expression marker', 'before {{ acc.camera }} after', true],
['a statement marker', '{% if acc.camera %}x{% endif %}', true],
['a template nested in an object', { a: { b: '{{ acc.view }}' } }, true],
['a template nested in an array', ['plain', '{{ acc.view }}'], true],
['a plain string', 'no templates here', false],
['an unmatched marker', 'an isolated {{ with no close', false],
['a non-string value', { count: 42, on: true }, false],
['an undefined value', undefined, false],
])('should detect %s', (_name, data, expected) => {
expect(TemplateManager.dataContainsTemplate(data)).toBe(expected);
});
});
describe('renderRecursively', () => {
it('should render string templates with camera context', () => {
const renderer = new TemplateRenderer();
it('should render string templates with camera context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(hass, 'Camera: {{ acc.camera }}', {
const result = manager.renderRecursively(hass, 'Camera: {{ acc.camera }}', {
conditionState: { camera: 'camera.office' },
});
expect(result).toBe('Camera: camera.office');
});
it('should render string templates with view context', () => {
const renderer = new TemplateRenderer();
it('should render string templates with view context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(hass, 'View: {{ acc.view }}', {
const result = manager.renderRecursively(hass, 'View: {{ acc.view }}', {
conditionState: { view: 'live' },
});
expect(result).toBe('View: live');
});
it('should render string templates with the acc context', () => {
const renderer = new TemplateRenderer();
it('should render string templates with the acc context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
'{{ acc.camera }} - {{ acc.view }}',
{
@@ -39,11 +121,12 @@ describe('TemplateRenderer', () => {
expect(result).toBe('camera.front - clips');
});
it('should render templates in arrays', () => {
const renderer = new TemplateRenderer();
it('should render templates in arrays', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
['{{ acc.camera }}', 'static', '{{ acc.view }}'],
{ conditionState: { camera: 'camera.office', view: 'live' } },
@@ -51,11 +134,12 @@ describe('TemplateRenderer', () => {
expect(result).toEqual(['camera.office', 'static', 'live']);
});
it('should render templates in object values', () => {
const renderer = new TemplateRenderer();
it('should render templates in object values', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
{ camera: '{{ acc.camera }}', view: '{{ acc.view }}', static: 'value' },
{ conditionState: { camera: 'camera.office', view: 'live' } },
@@ -63,11 +147,12 @@ describe('TemplateRenderer', () => {
expect(result).toEqual({ camera: 'camera.office', view: 'live', static: 'value' });
});
it('should render templates in nested objects', () => {
const renderer = new TemplateRenderer();
it('should render templates in nested objects', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
{ outer: { inner: '{{ acc.camera }}' } },
{ conditionState: { camera: 'camera.office' } },
@@ -75,27 +160,30 @@ describe('TemplateRenderer', () => {
expect(result).toEqual({ outer: { inner: 'camera.office' } });
});
it('should return non-string/array/object values unchanged', () => {
const renderer = new TemplateRenderer();
it('should return non-string/array/object values unchanged', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
expect(renderer.renderRecursively(hass, 42)).toBe(42);
expect(renderer.renderRecursively(hass, true)).toBe(true);
expect(renderer.renderRecursively(hass, null)).toBe(null);
expect(manager.renderRecursively(hass, 42)).toBe(42);
expect(manager.renderRecursively(hass, true)).toBe(true);
expect(manager.renderRecursively(hass, null)).toBe(null);
});
it('should render strings without templates unchanged', () => {
const renderer = new TemplateRenderer();
it('should render strings without templates unchanged', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
expect(renderer.renderRecursively(hass, 'hello world')).toBe('hello world');
expect(manager.renderRecursively(hass, 'hello world')).toBe('hello world');
});
it('should render with a top-level stock trigger context', () => {
const renderer = new TemplateRenderer();
it('should render with a top-level stock trigger context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(hass, '{{ trigger.to_state.state }}', {
const result = manager.renderRecursively(hass, '{{ trigger.to_state.state }}', {
triggerData: {
platform: 'state',
entity_id: 'binary_sensor.door',
@@ -105,11 +193,12 @@ describe('TemplateRenderer', () => {
expect(result).toBe('on');
});
it('should render with a top-level card trigger context', () => {
const renderer = new TemplateRenderer();
it('should render with a top-level card trigger context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(hass, '{{ trigger.to_acc.camera }}', {
const result = manager.renderRecursively(hass, '{{ trigger.to_acc.camera }}', {
triggerData: {
platform: 'acc',
type: 'camera',
@@ -120,21 +209,23 @@ describe('TemplateRenderer', () => {
expect(result).toBe('camera.backyard');
});
it('should render with config context', () => {
const renderer = new TemplateRenderer();
it('should render with config context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(hass, '{{ acc.config.view.default }}', {
const result = manager.renderRecursively(hass, '{{ acc.config.view.default }}', {
conditionState: { config: createConfig({ view: { default: 'clips' } }) },
});
expect(result).toBe('clips');
});
it('should render with mediaData context', () => {
const renderer = new TemplateRenderer();
it('should render with mediaData context', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
'Title: {{ acc.media.title }}, Folder: {{ acc.media.is_folder }}',
{
@@ -144,11 +235,12 @@ describe('TemplateRenderer', () => {
expect(result).toBe('Title: Test Media, Folder: false');
});
it('should render with combined context options', () => {
const renderer = new TemplateRenderer();
it('should render with combined context options', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursively(
const result = manager.renderRecursively(
hass,
'{{ acc.camera }} - {{ acc.media.title }}',
{
@@ -159,21 +251,23 @@ describe('TemplateRenderer', () => {
expect(result).toBe('camera.office - My Video');
});
it('should return undefined context when no options provided', () => {
const renderer = new TemplateRenderer();
it('should return undefined context when no options provided', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
// Without options, templates referencing acc should render empty.
const result = renderer.renderRecursively(hass, 'Value: {{ acc.camera }}');
const result = manager.renderRecursively(hass, 'Value: {{ acc.camera }}');
expect(result).toBe('Value:');
});
it('should return undefined context when options have no relevant data', () => {
const renderer = new TemplateRenderer();
it('should return undefined context when options have no relevant data', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
// Empty conditionState without camera or view should not create context.
const result = renderer.renderRecursively(hass, 'Value: {{ acc.camera }}', {
const result = manager.renderRecursively(hass, 'Value: {{ acc.camera }}', {
conditionState: {},
});
expect(result).toBe('Value:');
@@ -181,11 +275,12 @@ describe('TemplateRenderer', () => {
});
describe('renderRecursivelyAsType', () => {
it('should render in place while preserving the input structure', () => {
const renderer = new TemplateRenderer();
it('should render in place while preserving the input structure', async () => {
const manager = new TemplateManager();
await manager.loadRenderer();
const hass = createHASS();
const result = renderer.renderRecursivelyAsType(
const result = manager.renderRecursivelyAsType(
hass,
{ camera: '{{ acc.camera }}', static: 'value' },
{ conditionState: { camera: 'camera.office' } },
tests/card-controller/templates/renderer-via-event.test.ts
+32
View File
@@ -0,0 +1,32 @@
import { describe, expect, it, vi } from 'vitest';
import { mock } from 'vitest-mock-extended';
import type { TemplateRenderer } from '../../../src/card-controller/templates/index';
import {
getTemplateRendererViaEvent,
type TemplateRendererGetEvent,
} from '../../../src/card-controller/templates/renderer-via-event';
// @vitest-environment jsdom
describe('getTemplateRendererViaEvent', () => {
it('should dispatch event and retrieve template renderer', () => {
const element = document.createElement('div');
const templateRenderer = mock<TemplateRenderer>();
const handler = vi.fn().mockImplementation((ev: TemplateRendererGetEvent) => {
ev.templateRenderer = templateRenderer;
});
element.addEventListener('advanced-camera-card:template-renderer:get', handler);
expect(getTemplateRendererViaEvent(element)).toBe(templateRenderer);
});
it('should return null when no template renderer is provided', () => {
const element = document.createElement('div');
const handler = vi.fn();
element.addEventListener('advanced-camera-card:template-renderer:get', handler);
expect(getTemplateRendererViaEvent(element)).toBeNull();
});
});