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
+18 -15
View File
@@ -4,6 +4,7 @@ import { mock } from 'vitest-mock-extended';
import { FoldersExecutor } from '../../../src/card-controller/folders/executor';
import type { HAFoldersEngine } from '../../../src/card-controller/folders/ha/engine';
import type { FolderQuery } from '../../../src/card-controller/folders/types';
import { TemplateManager } from '../../../src/card-controller/templates';
import type { FolderConfig } from '../../../src/config/schema/folders';
import { QuerySource } from '../../../src/query-source';
import type { Endpoint } from '../../../src/types';
@@ -14,6 +15,8 @@ vi.mock('../../../src/card-controller/folders/ha/engine');
vi.mock('../../../../src/utils/ha/download');
describe('FoldersExecutor', () => {
const templateManager = new TemplateManager();
afterEach(() => {
vi.clearAllMocks();
});
@@ -21,7 +24,7 @@ describe('FoldersExecutor', () => {
describe('getItemCapabilities', () => {
it('should not get capabilities for non-folder media', () => {
const item = new TestViewMedia({ folder: null });
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(executor.getItemCapabilities(item)).toBeNull();
});
@@ -31,7 +34,7 @@ describe('FoldersExecutor', () => {
type: 'UNKNOWN',
} as unknown as FolderConfig;
const item = new TestViewMedia({ folder });
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(executor.getItemCapabilities(item)).toBeNull();
});
@@ -47,7 +50,7 @@ describe('FoldersExecutor', () => {
const haFolderEngine = mock<HAFoldersEngine>();
haFolderEngine.getItemCapabilities.mockReturnValue(capabilities);
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});
@@ -60,7 +63,7 @@ describe('FoldersExecutor', () => {
const folder: FolderConfig = {
type: 'UNKNOWN',
} as unknown as FolderConfig;
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(executor.getDefaultQueryParameters(folder)).toBeNull();
});
@@ -75,7 +78,7 @@ describe('FoldersExecutor', () => {
};
haFolderEngine.getDefaultQueryParameters.mockReturnValue(expectedQuery);
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});
@@ -89,7 +92,7 @@ describe('FoldersExecutor', () => {
type: 'UNKNOWN',
} as unknown as FolderConfig;
const item = new TestViewMedia({ folder });
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(await executor.getDownloadPath(createHASS(), item)).toBeNull();
});
@@ -99,7 +102,7 @@ describe('FoldersExecutor', () => {
const haFolderEngine = mock<HAFoldersEngine>();
haFolderEngine.getDownloadPath.mockResolvedValue(endpoint);
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});
const item = new TestViewMedia({ folder: createFolder() });
@@ -113,7 +116,7 @@ describe('FoldersExecutor', () => {
type: 'UNKNOWN',
} as unknown as FolderConfig;
const item = new TestViewMedia({ folder });
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
await executor.favorite(createHASS(), item, true);
@@ -122,7 +125,7 @@ describe('FoldersExecutor', () => {
it('should favorite', async () => {
const haFolderEngine = mock<HAFoldersEngine>();
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});
@@ -147,7 +150,7 @@ describe('FoldersExecutor', () => {
const haFolderEngine = mock<HAFoldersEngine>();
haFolderEngine.generateChildFolderQuery.mockReturnValue(query);
const executor = new FoldersExecutor({ ha: haFolderEngine });
const executor = new FoldersExecutor(templateManager, { ha: haFolderEngine });
expect(executor.generateChildFolderQuery(query, viewFolder)).toEqual(query);
expect(haFolderEngine.generateChildFolderQuery).toBeCalledWith(query, viewFolder);
@@ -163,7 +166,7 @@ describe('FoldersExecutor', () => {
path: [{ ha: { id: 'media-source://' } }],
};
const viewFolder = new ViewFolder(folder, []);
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(executor.generateChildFolderQuery(query, viewFolder)).toBeNull();
});
@@ -175,7 +178,7 @@ describe('FoldersExecutor', () => {
folder: { type: 'UNKNOWN' },
} as unknown as FolderQuery;
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(await executor.expandFolder(createHASS(), query)).toBeNull();
});
@@ -197,7 +200,7 @@ describe('FoldersExecutor', () => {
const haFolderEngine = mock<HAFoldersEngine>();
haFolderEngine.expandFolder.mockResolvedValue([folderItem, mediaItem, folderItem]);
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});
const hass = createHASS();
@@ -216,7 +219,7 @@ describe('FoldersExecutor', () => {
type: 'UNKNOWN',
} as unknown as FolderConfig;
const query: FolderQuery = { source: QuerySource.Folder, folder, path: [{}] };
const executor = new FoldersExecutor();
const executor = new FoldersExecutor(templateManager);
expect(executor.areResultsFresh(new Date(), query)).toBe(true);
});
@@ -227,7 +230,7 @@ describe('FoldersExecutor', () => {
const haFolderEngine = mock<HAFoldersEngine>();
haFolderEngine.areResultsFresh.mockReturnValue(false);
const executor = new FoldersExecutor({
const executor = new FoldersExecutor(templateManager, {
ha: haFolderEngine,
});