vite-plugin-static-twig 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# vite-plugin-static-twig
+
+A Vite plugin that compiles [Twig](https://github.com/twigjs/twig.js) templates into static HTML pages, with full dev-server HMR and multi-locale support.
+
+- Renders all `.twig` files under a configurable pages directory to HTML at build time
+- Watches templates and translation JSON files in dev mode and triggers a full browser reload on change
+- Injects hashed Vite asset paths (JS / CSS) from the manifest into every rendered page
+- Resolves bare Twig template references (`extends`, `include`, `embed`, `import`, `from`) relative to a shared templates root
+- Serves pre-rendered HTML from the output directory via a Connect middleware during `vite dev`
+- Computes relative `path` prefixes so pages at any nesting depth can reference root-level assets
+
+---
+
+## Requirements
+
+- **Node.js** >= 18
+- **Vite** >= 4 (peer dependency)
+
+---
+
+## Installation
+
+```shell
+npm install vite-plugin-static-twig
+```
+
+---
+
+## Usage
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import staticPagesPlugin from 'vite-plugin-static-twig';
+
+export default defineConfig({
+    plugins: [
+        staticPagesPlugin({
+            srcDir: 'src',
+            staticDir: 'src/templates/pages',
+            templatesDir: 'src/templates',
+            translationsDir: 'src/translations',
+            slugMapPath: 'src/js/json/translations.json',
+            locales: ['en', 'fr', 'nl', 'de'],
+            defaultLocale: 'en',
+            scriptsEntryKey: 'src/js/scripts.js',
+        })
+    ]
+});
+```
+
+---
+
+## Options
+
+All options are optional and fall back to sensible defaults.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `srcDir` | `string` | `'src'` | Root source directory. |
+| `staticDir` | `string` | `'src/templates/pages'` | Directory containing Twig page entry files. Files prefixed with `_` are skipped. |
+| `templatesDir` | `string` | `'src/templates'` | Shared Twig templates directory (layouts, partials, macros). |
+| `translationsDir` | `string` | `'src/translations'` | Directory containing JSON translation files. Must include `global.json` plus one file per locale (e.g. `en.json`). |
+| `slugMapPath` | `string` | `'src/js/json/translations.json'` | Project-relative path to a JSON slug translation map used to build language-switcher `href` values at build time. Set to `null` to disable. |
+| `useViteAssetsInBuild` | `boolean` | `true` | When `true`, reads the Vite manifest and injects hashed JS/CSS paths into every rendered page. |
+| `locales` | `string[]` | `['fr','en','nl','de']` | Locale codes recognised in directory names. The locale is inferred by finding one of these as a path segment. Pass `[]` for non-localised sites. |
+| `defaultLocale` | `string` | `'fr'` | Fallback locale used when none of the `locales` are found in the file path. Also used for pages placed at the root of `staticDir`. |
+| `scriptsEntryKey` | `string` | `'src/js/scripts.js'` | The Vite manifest key for the JS entry point. Used to look up the hashed JS and CSS filenames. |
+| `filters` | `Array<{ name: string, fn: Function }>` | `[]` | Additional Twig filters to register alongside the built-ins. Each entry is passed directly to `Twig.extendFilter(name, fn)`. |
+
+---
+
+## Template variables
+
+The following variables are available in every rendered Twig page.
+
+| Variable | Description |
+|---|---|
+| `{{ locale }}` | Current language code (e.g. `en`). |
+| `{{ path }}` | Relative prefix back to the `dist/` root (e.g. `../` for pages one level deep). Use this to prefix all asset URLs. |
+| `{{ isProduction }}` | `true` during `vite build`. |
+| `{{ useViteDevServer }}` | `true` during `vite dev`. |
+| `{{ useViteAssets }}` | `true` in production when `useViteAssetsInBuild` is enabled. |
+| `{{ viteAssets.js }}` | Hashed JS filename from the Vite manifest (production only). |
+| `{{ viteAssets.css }}` | Hashed CSS filename from the Vite manifest (production only). |
+| `{{ langSwitcherUrls }}` | Map of `{ targetLocale: relativeUrl }` for language-switcher links (requires `slugMapPath`). |
+
+All top-level keys from `global.json` and the current locale JSON file are also injected as Twig variables.
+
+---
+
+## Translation files
+
+Place one JSON file per locale and a `global.json` for shared keys inside `translationsDir`:
+
+```
+src/translations/
+├── global.json   ← merged into every page regardless of locale
+├── en.json
+├── fr.json
+├── nl.json
+└── de.json
+```
+
+---
+
+## Page conventions
+
+- Every `.twig` file under `staticDir` that does **not** start with `_` is compiled to HTML.
+- The locale is detected from the containing directory name (e.g. `pages/en/my-page.twig` → locale `en`).
+- Pages at the root of `staticDir` use `defaultLocale`.
+- Bare template references in `extends`, `include`, `embed`, `import`, and `from` tags are automatically resolved relative to `templatesDir`. Paths starting with `.` or `/` are used as-is.
+
+---
+
+## Custom Twig filters
+
+Two filters are registered automatically.
+
+### `external_links`
+
+Adds `target="_blank"`, `rel="noopener noreferrer"`, and a visually hidden screen-reader label to external links and file download links inside an HTML string.
+
+```twig
+{{ content|external_links(locale) }}
+```
+
+Recognised download extensions: `pdf`, `doc`, `docx`, `xls`, `xlsx`, `pptx`, `zip`.
+
+Screen-reader labels are resolved from a built-in map for `fr`, `nl`, `de`, and `en`. Unknown locales fall back to the French label.
+
+### `entity_encode`
+
+Encodes `mailto:` and `tel:` link `href` values and their visible text as HTML character entities to deter scraper harvesting.
+
+```twig
+{{ content|entity_encode }}
+```
+
+### Registering additional filters
+
+Pass a `filters` array to the plugin to register your own filters alongside the built-ins.
+
+```js
+// vite.config.js
+import staticPagesPlugin from 'vite-plugin-static-twig';
+
+export default {
+    plugins: [
+        staticPagesPlugin({
+            filters: [
+                { name: 'uppercase', fn: (value) => value?.toUpperCase() ?? value },
+                { name: 'prefix',    fn: (value, [pfx = '']) => `${pfx}${value}` }
+            ]
+        })
+    ]
+};
+```
+
+Filter functions can also be imported from a separate file to keep `vite.config.js` tidy:
+
+```js
+// src/twig-filters.js
+export const filters = [
+    { name: 'uppercase', fn: (value) => value?.toUpperCase() ?? value },
+    { name: 'prefix',    fn: (value, [pfx = '']) => `${pfx}${value}` }
+];
+```
+
+```js
+// vite.config.js
+import { filters } from './src/twig-filters.js';
+import staticPagesPlugin from 'vite-plugin-static-twig';
+
+export default {
+    plugins: [staticPagesPlugin({ filters })]
+};
+```
+
+Each `fn` receives the filtered value as its first argument and an array of filter arguments as its second, matching the signature expected by `Twig.extendFilter`.
+
+---
+
+## Publishing a new version
+
+Pushing a tag that matches `v*` triggers the GitHub Actions workflow which runs `npm publish` automatically.
+
+```shell
+git tag v1.2.0
+git push origin v1.2.0
+```
+
+The workflow requires an `NPM_TOKEN` secret to be set in the GitHub repository settings (Settings → Secrets → Actions).
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "vite-plugin-static-twig",
+    "version": "1.0.0",
+    "description": "Vite plugin that renders Twig templates into static HTML pages, with dev-server HMR and multi-locale support.",
+    "type": "module",
+    "main": "./src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src"
+    ],
+    "keywords": [
+        "vite",
+        "vite-plugin",
+        "twig",
+        "static-site",
+        "html",
+        "i18n"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/michaeldk/vite-plugin-static-twig.git"
+    },
+    "bugs": {
+        "url": "https://github.com/michaeldk/vite-plugin-static-twig/issues"
+    },
+    "homepage": "https://github.com/michaeldk/vite-plugin-static-twig#readme",
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "twig": "^1.17.1"
+    },
+    "peerDependencies": {
+        "vite": ">=4"
+    },
+    "peerDependenciesMeta": {
+        "vite": {
+            "optional": false
+        }
+    }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { default } from './static-pages-plugin.js';

package/src/middleware/dist-url-rewrite.js

@@ -0,0 +1,271 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Creates a Connect-compatible middleware that rewrites incoming request URLs
+ * to their pre-built counterparts in the Vite output directory (`outDir`).
+ *
+ * This allows the Vite dev server to serve the statically rendered HTML pages
+ * (written to `outDir` by the Twig render step) as if they were first-class
+ * dev-server routes. For example, a request for `/fr/about` is transparently
+ * rewritten to `/<outDir>/fr/about.html`.
+ *
+ * URL resolution is cached with a short TTL and invalidated whenever the file
+ * watcher reports a change inside `outDir`. Vite-internal paths (`/@vite`,
+ * `/@fs`, etc.) are always bypassed without touching the cache.
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot - Absolute path to the project root.
+ * @param {string} options.outDir      - Absolute path to the Vite output directory.
+ * @param {import('chokidar').FSWatcher} options.watcher - Vite's file watcher instance.
+ * @returns {import('connect').HandleFunction} Express/Connect middleware function.
+ */
+function createDistUrlRewrite(options) {
+    const { projectRoot, outDir, watcher } = options;
+    const STAT_CACHE_TTL_MS = 1000;
+    const RESOLUTION_CACHE_TTL_MS = 1000;
+    const MAX_CACHE_ENTRIES = 1024;
+    const fileStatCache = new Map();
+    const resolutionCache = new Map();
+    const inFlightResolution = new Map();
+    const distBasePath = getDistPublicBasePath();
+
+    /**
+     * Returns the URL base path under which the output directory is served,
+     * expressed as an absolute-style path string (e.g. `'/dist'` or `'/'`).
+     * Used to construct rewritten URLs and to skip requests that already point
+     * into the output directory.
+     *
+     * @returns {string}
+     */
+    function getDistPublicBasePath() {
+        const relativeOutDir = path.relative(projectRoot, outDir).split(path.sep).join('/');
+        return relativeOutDir ? `/${relativeOutDir}` : '/';
+    }
+
+    /**
+     * Evicts the oldest entry from `map` if it has reached `MAX_CACHE_ENTRIES`.
+     * Keeps memory usage bounded without a full flush.
+     *
+     * @param {Map} map
+     */
+    function trimCache(map) {
+        if (map.size < MAX_CACHE_ENTRIES) {
+            return;
+        }
+        const firstKey = map.keys().next().value;
+        if (firstKey !== undefined) {
+            map.delete(firstKey);
+        }
+    }
+
+    /**
+     * Clears all caches (file-stat, resolution, and in-flight).
+     * Called by the watcher when a file inside `outDir` changes, ensuring
+     * stale entries are not served after a re-render.
+     */
+    function clearCaches() {
+        fileStatCache.clear();
+        resolutionCache.clear();
+        inFlightResolution.clear();
+    }
+
+    if (watcher && typeof watcher.on === 'function') {
+        const invalidateOnSourceChange = (filePath) => {
+            const absolutePath = path.resolve(projectRoot, filePath);
+            if (isWithinOutDir(absolutePath)) {
+                clearCaches();
+            }
+        };
+        watcher.on('add', invalidateOnSourceChange);
+        watcher.on('change', invalidateOnSourceChange);
+        watcher.on('unlink', invalidateOnSourceChange);
+    }
+
+    /**
+     * Returns true if `absPath` is equal to, or nested inside, the resolved
+     * output directory. Used to guard against path-traversal candidates.
+     *
+     * @param {string} absPath - Absolute path to check.
+     * @returns {boolean}
+     */
+    function isWithinOutDir(absPath) {
+        const normalizedOutDir = path.resolve(outDir);
+        const normalizedTarget = path.resolve(absPath);
+        return (
+            normalizedTarget === normalizedOutDir ||
+            normalizedTarget.startsWith(`${normalizedOutDir}${path.sep}`)
+        );
+    }
+
+    /**
+     * Produces an ordered list of candidate file paths (relative to `outDir`)
+     * that could satisfy a given URL pathname. Resolution order:
+     * - `/`            → `index.html`
+     * - `/foo/`        → `foo/index.html`
+     * - `/foo.ext`     → `foo.ext`  (has extension — only one candidate)
+     * - `/foo`         → `foo`, `foo.html`, `foo/index.html`
+     *
+     * @param {string} pathname - URL pathname (e.g. `/fr/about`).
+     * @returns {string[]} Ordered candidates, relative to `outDir`.
+     */
+    function buildDistCandidates(pathname) {
+        const cleaned = pathname.replace(/^\/+/, '');
+        if (!cleaned) {
+            return ['index.html'];
+        }
+
+        if (cleaned.endsWith('/')) {
+            return [`${cleaned}index.html`];
+        }
+
+        if (path.extname(cleaned)) {
+            return [cleaned];
+        }
+
+        return [cleaned, `${cleaned}.html`, `${cleaned}/index.html`];
+    }
+
+    /**
+     * Checks whether `candidatePath` points to an existing file, with results
+     * cached for `STAT_CACHE_TTL_MS` milliseconds to avoid repeated syscalls.
+     *
+     * @param {string} candidatePath - Absolute path to check.
+     * @returns {Promise<boolean>}
+     */
+    async function isExistingFile(candidatePath) {
+        const now = Date.now();
+        const cached = fileStatCache.get(candidatePath);
+        if (cached && cached.expiresAt > now) {
+            return cached.isFile;
+        }
+
+        let isFile = false;
+        try {
+            const stat = await fs.promises.stat(candidatePath);
+            isFile = stat.isFile();
+        } catch (error) {
+            if (error && error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+                throw error;
+            }
+        }
+
+        trimCache(fileStatCache);
+        fileStatCache.set(candidatePath, {
+            isFile,
+            expiresAt: now + STAT_CACHE_TTL_MS
+        });
+        return isFile;
+    }
+
+    /**
+     * Resolves a URL pathname to an existing file path relative to `outDir`
+     * by trying the candidates returned by `buildDistCandidates` in order.
+     *
+     * Results are cached for `RESOLUTION_CACHE_TTL_MS` milliseconds.
+     * Concurrent calls for the same pathname share a single in-flight promise
+     * to prevent duplicate filesystem lookups.
+     *
+     * @param {string} pathname - URL pathname to resolve (e.g. `/fr/about`).
+     * @returns {Promise<string|null>} Relative path inside `outDir`, or `null` if not found.
+     */
+    async function resolveExistingDistPath(pathname) {
+        const now = Date.now();
+        const cached = resolutionCache.get(pathname);
+        if (cached && cached.expiresAt > now) {
+            return cached.value;
+        }
+
+        if (inFlightResolution.has(pathname)) {
+            return inFlightResolution.get(pathname);
+        }
+
+        const resolutionPromise = (async () => {
+            const candidates = buildDistCandidates(pathname);
+            for (const candidate of candidates) {
+                const candidatePath = path.resolve(outDir, candidate);
+                if (!isWithinOutDir(candidatePath)) {
+                    continue;
+                }
+                if (await isExistingFile(candidatePath)) {
+                    trimCache(resolutionCache);
+                    resolutionCache.set(pathname, {
+                        value: candidate,
+                        expiresAt: Date.now() + RESOLUTION_CACHE_TTL_MS
+                    });
+                    return candidate;
+                }
+            }
+
+            trimCache(resolutionCache);
+            resolutionCache.set(pathname, {
+                value: null,
+                expiresAt: Date.now() + RESOLUTION_CACHE_TTL_MS
+            });
+            return null;
+        })();
+
+        inFlightResolution.set(pathname, resolutionPromise);
+        try {
+            return await resolutionPromise;
+        } finally {
+            inFlightResolution.delete(pathname);
+        }
+    }
+
+    /**
+     * Connect middleware. Rewrites `req.url` for GET/HEAD requests whose
+     * pathname maps to an existing file in `outDir`, then calls `next()`.
+     * Passes through unchanged for Vite-internal paths, unresolvable paths,
+     * and non-GET/HEAD methods.
+     *
+     * @param {import('http').IncomingMessage} req
+     * @param {import('http').ServerResponse}  res
+     * @param {Function} next
+     * @returns {Promise<void>}
+     */
+    return async function distUrlRewriteMiddleware(req, res, next) {
+        if (!req.url || (req.method !== 'GET' && req.method !== 'HEAD')) {
+            return next();
+        }
+
+        let parsed;
+        try {
+            parsed = new URL(req.url, 'http://localhost');
+        } catch (_error) {
+            return next();
+        }
+
+        const pathname = parsed.pathname;
+        const shouldBypass =
+            pathname.startsWith('/@vite') ||
+            pathname.startsWith('/@fs/') ||
+            pathname.startsWith('/@id/') ||
+            pathname.startsWith('/__vite') ||
+            pathname.startsWith('/node_modules/') ||
+            pathname.startsWith('/src/') ||
+            pathname.startsWith(`${distBasePath}/`);
+
+        if (shouldBypass) {
+            return next();
+        }
+
+        try {
+            const matchedDistPath = await resolveExistingDistPath(pathname);
+            if (!matchedDistPath) {
+                return next();
+            }
+
+            req.url =
+                distBasePath === '/'
+                    ? `/${matchedDistPath}${parsed.search}`
+                    : `${distBasePath}/${matchedDistPath}${parsed.search}`;
+        } catch (error) {
+            console.error('[dist-url-rewrite] path resolution failed:', error);
+        }
+
+        return next();
+    };
+}
+
+export { createDistUrlRewrite };

package/src/site-utils.js

@@ -0,0 +1,99 @@
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+
+/**
+ * Creates a collection of file-system utility helpers scoped to a given
+ * project root. Paths that begin with an underscore-prefixed segment are
+ * treated as private and are skipped during directory walks.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {{ walkFiles: Function, ensureDir: Function, copyFileWithParents: Function, loadJson: Function }}
+ */
+function createSiteUtils(projectRoot) {
+    /**
+     * Returns true if any segment of `absPath` (relative to `projectRoot`)
+     * starts with an underscore, indicating the path should be ignored.
+     *
+     * @param {string} absPath - Absolute path to test.
+     * @returns {boolean}
+     */
+    function shouldIgnorePath(absPath) {
+        const rel = path.relative(projectRoot, absPath);
+        const segments = rel.split(path.sep);
+        return segments.some((segment) => segment.startsWith('_'));
+    }
+
+    /**
+     * Recursively collects all file paths inside `dirPath`, skipping any
+     * entry whose path contains an underscore-prefixed segment.
+     *
+     * @param {string} dirPath - Absolute path of the directory to walk.
+     * @returns {Promise<string[]>} Flat list of absolute file paths.
+     */
+    async function walkFiles(dirPath) {
+        const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+        const files = [];
+
+        for (const entry of entries) {
+            const entryPath = path.join(dirPath, entry.name);
+            if (shouldIgnorePath(entryPath)) {
+                continue;
+            }
+
+            if (entry.isDirectory()) {
+                files.push(...(await walkFiles(entryPath)));
+                continue;
+            }
+
+            files.push(entryPath);
+        }
+
+        return files;
+    }
+
+    /**
+     * Creates `dirPath` and any missing parent directories (equivalent to `mkdir -p`).
+     *
+     * @param {string} dirPath - Absolute path of the directory to create.
+     * @returns {Promise<void>}
+     */
+    async function ensureDir(dirPath) {
+        await fsp.mkdir(dirPath, { recursive: true });
+    }
+
+    /**
+     * Copies a file to `targetPath`, creating any missing parent directories first.
+     *
+     * @param {string} sourcePath - Absolute path of the source file.
+     * @param {string} targetPath - Absolute path of the destination file.
+     * @returns {Promise<void>}
+     */
+    async function copyFileWithParents(sourcePath, targetPath) {
+        await ensureDir(path.dirname(targetPath));
+        await fsp.copyFile(sourcePath, targetPath);
+    }
+
+    /**
+     * Reads and parses a JSON file. Returns an empty object if the file does
+     * not exist, so callers can safely spread the result without null-checking.
+     *
+     * @param {string} jsonPath - Absolute path to the JSON file.
+     * @returns {Promise<object>}
+     */
+    async function loadJson(jsonPath) {
+        if (!fs.existsSync(jsonPath)) {
+            return {};
+        }
+        return JSON.parse(await fsp.readFile(jsonPath, 'utf8'));
+    }
+
+    return {
+        walkFiles,
+        ensureDir,
+        copyFileWithParents,
+        loadJson
+    };
+}
+
+export { createSiteUtils };

package/src/static-pages-plugin.js

@@ -0,0 +1,263 @@
+import path from 'path';
+import { createSiteUtils } from './site-utils.js';
+import { createTwigPagesTask } from './tasks/twig-pages.js';
+import { createDistUrlRewrite } from './middleware/dist-url-rewrite.js';
+
+/**
+ * Vite plugin that renders Twig templates into static HTML pages during both
+ * development (via a dev-server middleware) and production builds.
+ *
+ * In dev mode the plugin watches the source directories and triggers a full
+ * browser reload whenever a relevant file changes, using a render-coalescing
+ * strategy to avoid concurrent renders.
+ *
+ * @param {object}   [options]
+ * @param {string}   [options.srcDir='src']                                  - Root source directory.
+ * @param {string}   [options.staticDir='src/templates/pages']               - Twig page entry files.
+ * @param {string}   [options.templatesDir='src/templates']                  - Shared Twig templates.
+ * @param {string}   [options.translationsDir='src/translations']            - JSON translation files.
+ * @param {string}   [options.slugMapPath='src/js/json/translations.json']   - URL slug translation map used to build lang-switcher hrefs at build time.
+ * @param {boolean}  [options.useViteAssetsInBuild=true]                     - Inject Vite manifest assets into rendered HTML.
+ * @param {string[]} [options.locales=['fr','en','nl','de']]                  - Locale codes to detect from directory names.
+ * @param {string}   [options.defaultLocale='fr']                            - Fallback locale when none is detected from the path.
+ * @param {string}   [options.scriptsEntryKey='src/js/scripts.js']           - Vite manifest key for the JS/CSS entry point.
+ * @param {Array<{name:string, fn:Function}>} [options.filters=[]]          - Additional Twig filters to register. Each entry is `{ name, fn }` passed directly to `Twig.extendFilter`.
+ * @returns {import('vite').Plugin}
+ */
+function staticPagesPlugin(options = {}) {
+    const {
+        srcDir = 'src',
+        staticDir = 'src/templates/pages',
+        templatesDir = 'src/templates',
+        translationsDir = 'src/translations',
+        slugMapPath = 'src/js/json/translations.json',
+        useViteAssetsInBuild = true,
+        locales = ['fr', 'en', 'nl', 'de'],
+        defaultLocale = 'fr',
+        scriptsEntryKey = 'src/js/scripts.js',
+        filters = []
+    } = options;
+
+    let config;
+    let projectRoot;
+    let devServer = null;
+    let tasks = null;
+
+    // Render coalescing: if a file changes while a render is already running,
+    // we don't start a second concurrent render. Instead we set rerenderQueued=true
+    // so the active render loops once more when done, draining all pending requests.
+    let isRendering = false;
+    let rerenderQueued = false;
+    let fullReloadQueued = false;
+
+    /**
+     * Instantiates the utility helpers and the Twig render task, bound to the
+     * resolved Vite config. Called once inside `configResolved`.
+     *
+     * @returns {{ utils: object, twigPagesTask: object }}
+     */
+    function buildTasks() {
+        const utils = createSiteUtils(projectRoot);
+        const twigPagesTask = createTwigPagesTask({
+            srcDir,
+            staticDir,
+            templatesDir,
+            translationsDir,
+            slugMapPath,
+            useViteAssetsInBuild,
+            locales,
+            defaultLocale,
+            scriptsEntryKey,
+            filters,
+            projectRoot,
+            outDir: path.resolve(projectRoot, config.build.outDir),
+            walkFiles: utils.walkFiles,
+            ensureDir: utils.ensureDir,
+            loadJson: utils.loadJson
+        });
+
+        return {
+            utils,
+            twigPagesTask
+        };
+    }
+
+    /**
+     * Returns true if `absPath` is inside any of the three watched source
+     * directories (static pages, templates, or translations).
+     * Does **not** filter by file extension.
+     *
+     * @param {string} absPath - Absolute path to check.
+     * @returns {boolean}
+     */
+    function isInWatchedDirectory(absPath) {
+        const relativePath = path.relative(projectRoot, absPath);
+        if (relativePath.startsWith('..')) {
+            return false;
+        }
+
+        const staticPrefix = `${staticDir}${path.sep}`;
+        const templatesPrefix = `${templatesDir}${path.sep}`;
+        const translationsPrefix = `${translationsDir}${path.sep}`;
+
+        return (
+            relativePath === staticDir ||
+            relativePath === templatesDir ||
+            relativePath === translationsDir ||
+            relativePath.startsWith(staticPrefix) ||
+            relativePath.startsWith(templatesPrefix) ||
+            relativePath.startsWith(translationsPrefix)
+        );
+    }
+
+    /**
+     * Registers every source file in the watched directories with Vite's watcher
+     * so that `hotUpdate` is triggered when they change. Only called in dev mode.
+     *
+     * @param {import('vite').BuildContext} ctx - The Vite `buildStart` hook context.
+     * @returns {Promise<void>}
+     */
+    async function addWatchFiles(ctx) {
+        const staticRoot = path.join(projectRoot, staticDir);
+        const templatesRoot = path.join(projectRoot, templatesDir);
+        const translationsRoot = path.join(projectRoot, translationsDir);
+
+        const [staticFiles, templateFiles, translationFiles] = await Promise.all([
+            tasks.utils.walkFiles(staticRoot),
+            tasks.utils.walkFiles(templatesRoot),
+            tasks.utils.walkFiles(translationsRoot)
+        ]);
+
+        const twigFiles = staticFiles.filter((filePath) => path.extname(filePath).toLowerCase() === '.twig');
+        const extraFiles = slugMapPath ? [path.resolve(projectRoot, slugMapPath)] : [];
+        for (const filePath of [...twigFiles, ...templateFiles, ...translationFiles, ...extraFiles]) {
+            ctx.addWatchFile(filePath);
+        }
+    }
+
+    /**
+     * Builds the context object passed to `twigPagesTask.renderTwigPages`,
+     * derived from the current Vite command (`serve` vs `build`).
+     *
+     * @returns {{ isBuild: boolean, useViteDevServer: boolean, viteDevBase: string }}
+     */
+    function createRenderContext() {
+        return {
+            isBuild: config.command === 'build',
+            useViteDevServer: config.command === 'serve',
+            viteDevBase: '/'
+        };
+    }
+
+    /**
+     * Triggers a Twig re-render. Calls made while a render is already in progress
+     * are coalesced — the render loop processes them in sequence, never in parallel.
+     * @param {boolean} fullReload - Whether to send a full browser reload after rendering.
+     */
+    async function renderTwigPages(fullReload = false) {
+        rerenderQueued = true;
+        fullReloadQueued ||= fullReload;
+        if (isRendering) {
+            return;
+        }
+
+        isRendering = true;
+        try {
+            while (rerenderQueued) {
+                const shouldReload = fullReloadQueued;
+                rerenderQueued = false;
+                fullReloadQueued = false;
+
+                await tasks.twigPagesTask.renderTwigPages(createRenderContext());
+                if (shouldReload && devServer) {
+                    devServer.ws.send({ type: 'full-reload' });
+                }
+            }
+        } catch (error) {
+            console.error('[static-pages-plugin] render failed:', error);
+        } finally {
+            isRendering = false;
+        }
+    }
+
+    /**
+     * Determines whether a changed file should trigger a full Twig re-render.
+     *
+     * Returns `true` when the file is:
+     * - a `.twig` file inside any watched directory, OR
+     * - any file inside the templates or translations directories (changing a
+     *   layout or a translation string always invalidates every page).
+     *
+     * Returns `false` for paths outside the watched directories or for unrelated
+     * file types (e.g. static images inside the pages tree).
+     *
+     * @param {string} filePath - Absolute or project-relative path of the changed file.
+     * @returns {boolean}
+     */
+    function needsRerender(filePath) {
+        const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath);
+
+        if (slugMapPath && absolutePath === path.resolve(projectRoot, slugMapPath)) {
+            return true;
+        }
+
+        if (!isInWatchedDirectory(absolutePath)) {
+            return false;
+        }
+
+        const relativePath = path.relative(projectRoot, absolutePath);
+        const extension = path.extname(relativePath).toLowerCase();
+        const isTwig = extension === '.twig';
+        const templatesPrefix = `${templatesDir}${path.sep}`;
+        const translationsPrefix = `${translationsDir}${path.sep}`;
+        const isTemplateOrTranslation =
+            relativePath === templatesDir ||
+            relativePath === translationsDir ||
+            relativePath.startsWith(templatesPrefix) ||
+            relativePath.startsWith(translationsPrefix);
+
+        return isTwig || isTemplateOrTranslation;
+    }
+
+    return {
+        name: 'static-pages-plugin',
+        configResolved(resolvedConfig) {
+            config = resolvedConfig;
+            projectRoot = resolvedConfig.root;
+            tasks = buildTasks();
+        },
+        async buildStart() {
+            // Only register watch files in dev mode; build mode does not need them.
+            if (config.command === 'serve') {
+                await addWatchFiles(this);
+            }
+        },
+        async closeBundle() {
+            await tasks.twigPagesTask.renderTwigPages(createRenderContext());
+            console.log('Twig pages generated in output directory.');
+        },
+        async configureServer(server) {
+            devServer = server;
+            await renderTwigPages(false);
+            server.middlewares.use(
+                createDistUrlRewrite({
+                    projectRoot,
+                    outDir: path.resolve(projectRoot, config.build.outDir),
+                    watcher: server.watcher
+                })
+            );
+        },
+        hotUpdate({ file }) {
+            if (needsRerender(file)) {
+                // Fire-and-forget: hotUpdate must return synchronously, so we do not
+                // await. The render coalescing logic handles concurrent calls safely.
+                // Return empty array to suppress default HMR; renderTwigPages sends
+                // a full-reload itself once re-rendering is complete.
+                void renderTwigPages(true);
+                return [];
+            }
+        }
+    };
+}
+
+export default staticPagesPlugin;

package/src/tasks/twig-pages.js

@@ -0,0 +1,363 @@
+import fs from 'fs';
+import path from 'path';
+import Twig from 'twig';
+
+/**
+ * Creates a task that renders Twig page templates into static HTML files.
+ *
+ * Each `.twig` file under `staticDir` (excluding underscore-prefixed files)
+ * is treated as a page entry. Language is inferred from the directory structure,
+ * translations are loaded per language, and asset paths are made relative to
+ * each output file's location.
+ *
+ * @param {object}   options
+ * @param {string}   options.srcDir               - Root source directory.
+ * @param {string}   options.staticDir            - Directory containing Twig page entries.
+ * @param {string}   options.templatesDir         - Shared Twig templates directory.
+ * @param {string}   options.translationsDir      - Directory containing JSON translation files.
+ * @param {string}   [options.slugMapPath]        - Project-relative path to the URL slug translation map (JSON).
+ * @param {boolean}  options.useViteAssetsInBuild - Whether to inject Vite manifest assets.
+ * @param {string[]} [options.locales]            - List of locale codes to detect from directory names. Defaults to `['fr','en','nl','de']`.
+ * @param {string}   [options.defaultLocale]      - Locale used when none is detected from the path. Defaults to `'fr'`.
+ * @param {string}   [options.scriptsEntryKey]    - Vite manifest key for the JS entry point. Defaults to `'src/js/scripts.js'`.
+ * @param {string}   options.projectRoot          - Absolute project root path.
+ * @param {string}   options.outDir               - Absolute output directory path.
+ * @param {Function} options.walkFiles            - Async function to list files recursively.
+ * @param {Function} options.ensureDir            - Async function to create a directory tree.
+ * @param {Function} options.loadJson             - Async function to load a JSON file safely.
+ * @param {Array<{name:string, fn:Function}>} [options.filters=[]] - Additional Twig filters to register alongside the built-ins.
+ * @returns {{ renderTwigPages: Function }}
+ */
+function createTwigPagesTask(options) {
+    const {
+        srcDir,
+        staticDir,
+        templatesDir,
+        translationsDir,
+        slugMapPath,
+        useViteAssetsInBuild,
+        locales = ['fr', 'en', 'nl', 'de'],
+        defaultLocale = 'fr',
+        scriptsEntryKey = 'src/js/scripts.js',
+        filters = [],
+        projectRoot,
+        outDir,
+        walkFiles,
+        ensureDir,
+        loadJson
+    } = options;
+
+    const localePattern = new RegExp(`[\\\\/](${locales.join('|')})[\\\\/]`);
+
+    /**
+     * Infers the locale from a file path by looking for a language-code segment
+     * matching one of the configured `locales`. Defaults to `defaultLocale` if
+     * none is found.
+     *
+     * @param {string} filePath - Absolute or relative path to the Twig file.
+     * @returns {string}
+     */
+    function detectLanguage(filePath) {
+        const match = filePath.match(localePattern);
+        return match ? match[1] : defaultLocale;
+    }
+
+    /**
+     * Calculates the relative path prefix needed to reach the asset root from
+     * the output HTML file's location (e.g. `'../../'` for a file two levels deep).
+     * Returns an empty string for files at the root of the output directory.
+     *
+     * @param {string} filePath    - Absolute path to the source `.twig` file.
+     * @param {string} staticRoot  - Absolute path to the static pages root.
+     * @param {string} outputRoot  - Absolute path to the build output directory.
+     * @returns {string} Relative prefix ending with `/`, or empty string.
+     */
+    function calculateAssetPath(filePath, staticRoot, outputRoot) {
+        const outputPath = filePath.replace(/\.twig$/, '.html').replace(staticRoot, outputRoot);
+        const relativePath = path.relative(outputRoot, outputPath);
+        const dirname = path.dirname(relativePath);
+        const depth = dirname === '.' ? 0 : dirname.split(path.sep).length;
+        return depth > 0 ? '../'.repeat(depth) : '';
+    }
+
+    /**
+     * Builds a map of `{ targetLang: relativeUrl }` for the language-switcher
+     * links of a given page, resolved at build time from the slug translation map.
+     *
+     * For example, for `de/unbefristete-kombinierte-erlaubnis.html` it returns:
+     * ```
+     * {
+     *   nl: '../nl/gecombineerde-vergunning-onbepaalde-duur.html',
+     *   fr: '../fr/permis-unique-a-duree-illimitee.html',
+     *   en: '../en/permanent-single-permit.html'
+     * }
+     * ```
+     *
+     * Returns an empty object when the page has no translatable lang prefix or
+     * when any slug cannot be found in the map.
+     *
+     * @param {string} outputRelative - Relative output path, e.g. `de/page.html`.
+     * @param {string} lang           - Current page locale, e.g. `'de'`.
+     * @param {object} slugMap        - Parsed slug translation map (translations.json).
+     * @param {string} assetPath      - Relative prefix back to the output root (e.g. `'../'`).
+     * @returns {Record<string, string>}
+     */
+    function buildLangSwitcherUrls(outputRelative, lang, slugMap, assetPath) {
+        const normalized = outputRelative.split(path.sep).join('/');
+        const langPrefix = `${lang}/`;
+
+        if (!normalized.startsWith(langPrefix) || !slugMap?.[lang]) return {};
+
+        const slugs = normalized
+            .slice(langPrefix.length)
+            .replace(/\.html$/, '')
+            .split('/')
+            .filter(Boolean);
+
+        const indices = slugs.map(slug => slugMap[lang].indexOf(slug));
+        if (indices.some(i => i === -1)) return {};
+
+        const urls = {};
+        for (const targetLang of Object.keys(slugMap)) {
+            if (targetLang === lang || !slugMap[targetLang]) continue;
+
+            const translatedSlugs = indices.map(i => slugMap[targetLang][i]);
+            if (translatedSlugs.some(s => !s)) continue;
+
+            urls[targetLang] = `${assetPath}${targetLang}/${translatedSlugs.join('/')}.html`;
+        }
+
+        return urls;
+    }
+
+    /**
+     * Resolves a Vite manifest entry by trying `preferredKeys` first, then
+     * falling back to a predicate scan of all entries. Returns `undefined` if
+     * nothing matches.
+     *
+     * @param {object}   manifest         - Parsed `.vite/manifest.json`.
+     * @param {string[]} preferredKeys    - Manifest keys to check in order of preference.
+     * @param {Function} fallbackMatcher  - `(key, value) => boolean` used when no preferred key matches.
+     * @returns {object|undefined} The matched manifest entry, or `undefined`.
+     */
+    function getViteManifestEntry(manifest, preferredKeys, fallbackMatcher) {
+        for (const key of preferredKeys) {
+            if (manifest[key]) {
+                return manifest[key];
+            }
+        }
+        return Object.entries(manifest).find(([key, value]) => fallbackMatcher(key, value))?.[1];
+    }
+
+    /**
+     * Reads the Vite build manifest and extracts the hashed JS and CSS asset
+     * paths for the main `scripts` entry point.
+     * Returns `{ js: '', css: '' }` when the manifest does not exist (dev mode).
+     *
+     * @returns {Promise<{ js: string, css: string }>}
+     */
+    async function loadViteAssets() {
+        const manifestPath = path.join(outDir, '.vite', 'manifest.json');
+        if (!fs.existsSync(manifestPath)) {
+            return {};
+        }
+
+        const manifest = JSON.parse(await fs.promises.readFile(manifestPath, 'utf8'));
+        const entryBasename = path.basename(scriptsEntryKey);
+        const entryStem = path.basename(scriptsEntryKey, path.extname(scriptsEntryKey));
+        const scriptsEntry = getViteManifestEntry(
+            manifest,
+            [scriptsEntryKey, entryStem],
+            (key, value) => key.endsWith(entryBasename) || String(value?.file || '').includes(entryStem)
+        );
+
+        return {
+            js: scriptsEntry?.file || '',
+            css: scriptsEntry?.css?.[0] || ''
+        };
+    }
+
+    /**
+     * Registers custom Twig filters on the shared Twig instance:
+     *
+     * - `external_links` — Adds `target="_blank"`, `rel="noopener noreferrer"`,
+     *   and a screen-reader label to external URLs and file download links.
+     * - `entity_encode` — HTML-entity-encodes `mailto:` and `tel:` link hrefs
+     *   and their visible text to deter scraper harvesting.
+     *
+     * Safe to call multiple times; Twig silently overwrites existing filters.
+     */
+    function registerTwigFilters() {
+        Twig.extendFilter('external_links', function(value, lang = 'fr') {
+            if (!value || typeof value !== 'string') return value;
+
+            const externalLabels = {
+                fr: 'Nouvelle fenêtre',
+                nl: 'Nieuw venster',
+                de: 'neues Fenster',
+                en: 'New window'
+            };
+
+            const fileExtensions = ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'pptx', 'zip'];
+            const label = externalLabels[lang] || externalLabels.fr;
+
+            return value.replace(/<a([^>]*)>(.*?)<\/a>/gis, (match, attrs, text) => {
+                const hrefMatch = attrs.match(/href\s*=\s*["']([^"']+)["']/i);
+                if (!hrefMatch) return match;
+
+                const href = hrefMatch[1];
+                if (href.startsWith('#') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+                    return match;
+                }
+
+                const ext = href.split('?')[0].split('.').pop().toLowerCase();
+                const isDownload = fileExtensions.includes(ext);
+                const isExternal = /^(https?:\/\/|www\.)/i.test(href);
+
+                if (!isExternal && !isDownload) return match;
+
+                if (!/target\s*=\s*["']_blank["']/.test(attrs)) {
+                    attrs += ' target="_blank"';
+                }
+
+                if (!/rel\s*=/.test(attrs)) {
+                    attrs += ' rel="noopener noreferrer"';
+                }
+
+                if (!text.includes('sr-only')) {
+                    const labelText = isDownload ? `.${ext} — ${label}` : label;
+                    text += `<span class="sr-only"> (${labelText})</span>`;
+                }
+
+                return `<a${attrs}>${text}</a>`;
+            });
+        });
+
+        Twig.extendFilter('entity_encode', function(value) {
+            if (!value || typeof value !== 'string') return value;
+
+            const encode = (str) =>
+                str
+                    .split('')
+                    .map((char) => `&#${char.charCodeAt(0)};`)
+                    .join('');
+
+            return value.replace(
+                /<a\s([^>]*)>(.*?)<\/a>/gis,
+                (match, attrs, text) => {
+                    const hrefMatch = attrs.match(/href\s*=\s*["']((?:mailto|tel):[^"']+)["']/i);
+                    if (!hrefMatch) return match;
+
+                    const encodedAttrs = attrs.replace(
+                        /(href\s*=\s*["'])(?:mailto|tel):[^"']+(?=["'])/i,
+                        (_, prefix) => prefix + encode(hrefMatch[1])
+                    );
+
+                    return `<a ${encodedAttrs}>${encode(text)}</a>`;
+                }
+            );
+        });
+
+        for (const { name, fn } of filters) {
+            Twig.extendFilter(name, fn);
+        }
+    }
+
+    /**
+     * Renders every Twig page entry under `staticDir` to an HTML file in `outDir`.
+     *
+     * For each page the function:
+     * 1. Detects the locale from the file path and loads the matching translations.
+     * 2. Computes relative asset/template paths so the file works at any nesting depth.
+     * 3. Rewrites bare template references (e.g. `extends 'layout.twig'`) to
+     *    paths relative to the page file, since Twig requires resolvable paths.
+     * 4. Compiles and renders the template, strips blank lines, and writes the result.
+     *
+     * Throws if `isBuild && useViteAssetsInBuild` is true but the Vite manifest
+     * assets could not be loaded (indicating the JS/CSS build step was skipped).
+     *
+     * @param {{ isBuild: boolean, useViteDevServer: boolean, viteDevBase: string }} context
+     * @returns {Promise<void>}
+     */
+    async function renderTwigPages(context) {
+        const { isBuild, useViteDevServer, viteDevBase } = context;
+        registerTwigFilters();
+
+        const staticRoot = path.join(projectRoot, staticDir);
+        const templatesRoot = path.join(projectRoot, templatesDir);
+        const translationsRoot = path.join(projectRoot, translationsDir);
+
+        const globalVars = await loadJson(path.join(translationsRoot, 'global.json'));
+        const slugMap = slugMapPath ? await loadJson(path.join(projectRoot, slugMapPath)) : null;
+        const viteAssets = await loadViteAssets();
+        if (isBuild && useViteAssetsInBuild && (!viteAssets.js || !viteAssets.css)) {
+            throw new Error('Vite manifest assets are required for production Twig rendering.');
+        }
+
+        const allFiles = await walkFiles(staticRoot);
+        const pages = allFiles.filter((filePath) => {
+            const ext = path.extname(filePath).toLowerCase();
+            const basename = path.basename(filePath);
+            return ext === '.twig' && !basename.startsWith('_');
+        });
+
+        for (const pagePath of pages) {
+            const lang = detectLanguage(pagePath);
+            const translations = await loadJson(path.join(translationsRoot, `${lang}.json`));
+            const assetPath = calculateAssetPath(pagePath, staticRoot, outDir);
+            const outputRelative = path.relative(staticRoot, pagePath).replace(/\.twig$/, '.html');
+            const outputPath = path.join(outDir, outputRelative);
+
+            const langSwitcherUrls = slugMap
+                ? buildLangSwitcherUrls(outputRelative, lang, slugMap, assetPath)
+                : {};
+
+            const data = {
+                ...globalVars,
+                ...translations,
+                locale: lang,
+                assetPath,
+                langSwitcherUrls,
+                isProduction: isBuild,
+                useViteDevServer,
+                viteDevBase,
+                useViteAssets: isBuild && useViteAssetsInBuild,
+                viteAssets
+            };
+
+            const pageDir = path.dirname(pagePath);
+            const relativeTplsPath = path.relative(pageDir, templatesRoot).split(path.sep).join('/');
+            const templateContent = (await fs.promises.readFile(pagePath, 'utf8')).replace(
+                /(\{%\s*(?:extends|include|embed|import|from)\s+['"])([^'"]+?\.twig)(['"])/g,
+                (fullMatch, prefix, targetPath, suffix) => {
+                    if (targetPath.startsWith('.') || targetPath.startsWith('/')) {
+                        return fullMatch;
+                    }
+                    return `${prefix}${relativeTplsPath}/${targetPath}${suffix}`;
+                }
+            );
+
+            const compiled = Twig.twig({
+                data: templateContent,
+                path: pagePath,
+                base: templatesRoot,
+                rethrow: true
+            });
+
+            const html = compiled
+                .render(data)
+                .split('\n')
+                .filter((line) => line.trim() !== '')
+                .join('\n');
+
+            await ensureDir(path.dirname(outputPath));
+            await fs.promises.writeFile(outputPath, `${html}\n`, 'utf8');
+        }
+    }
+
+    return {
+        renderTwigPages
+    };
+}
+
+export { createTwigPagesTask };