@megabudino/stack-utils 1.5.0 → 2.0.0

package/dist/proxy/vite-plugin.js

@@ -0,0 +1,292 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildProxyIslandsClientEntryModule, extractProxyIslandsMetadata, extractViteCssFromJs, injectAutoWiredIslandsConfig, isCssLikeModuleId, needsAutoWiredAssets, toPublicAssetUrl } from './vite-plugin-core.js';
+const GENERATED_CLIENT_ENTRY_RELATIVE_PATH = '.svelte-kit/generated/stack-utils/proxy-islands.generated.ts';
+const AUTO_ENTRY_PLACEHOLDER = '__STACK_UTILS_PROXY_ISLANDS_ENTRY__';
+const AUTO_STYLES_PLACEHOLDER = '__STACK_UTILS_PROXY_ISLANDS_STYLES__';
+/**
+ * Dev URL for the combined islands stylesheet.
+ *
+ * In dev, `svelte/server`'s `render()` does not emit scoped component CSS into
+ * its `head` output and `vite-plugin-svelte` injects styles via a JS-runtime
+ * `<style>` append. That produces a flash because the styles arrive after the
+ * proxied HTML has already painted. We bridge the gap by serving a real
+ * stylesheet at this URL, sourced from the islands client entry's CSS deps,
+ * so the browser blocks render until styles are ready.
+ */
+const DEV_ISLANDS_CSS_URL = '/@stack-utils/proxy-islands.css';
+export function proxyIslands() {
+    let config;
+    let hooksFilePath = null;
+    let generatedClientEntryPath = null;
+    let latestMetadata = null;
+    let clientEntryRef = null;
+    const updateGeneratedClientEntry = async (hooksCode) => {
+        if (!hooksFilePath || !generatedClientEntryPath) {
+            return null;
+        }
+        const code = hooksCode ?? (await readFile(hooksFilePath, 'utf8'));
+        const metadata = extractProxyIslandsMetadata(code, hooksFilePath);
+        latestMetadata = metadata;
+        if (!metadata || !needsAutoWiredAssets(metadata)) {
+            return metadata;
+        }
+        const generatedClientEntry = buildProxyIslandsClientEntryModule(metadata, hooksFilePath, generatedClientEntryPath);
+        await mkdir(path.dirname(generatedClientEntryPath), { recursive: true });
+        await writeFile(generatedClientEntryPath, generatedClientEntry, 'utf8');
+        return metadata;
+    };
+    return {
+        name: 'proxy-islands',
+        enforce: 'pre',
+        configResolved(resolvedConfig) {
+            config = resolvedConfig;
+            hooksFilePath = findHooksServerFile(config.root);
+            generatedClientEntryPath = path.join(config.root, GENERATED_CLIENT_ENTRY_RELATIVE_PATH);
+        },
+        async buildStart() {
+            if (!hooksFilePath || !generatedClientEntryPath) {
+                return;
+            }
+            const metadata = await updateGeneratedClientEntry();
+            if (!metadata || !needsAutoWiredAssets(metadata)) {
+                return;
+            }
+            if (config.command === 'build' && !config.build.ssr) {
+                clientEntryRef = this.emitFile({
+                    type: 'chunk',
+                    id: generatedClientEntryPath,
+                    name: 'stack-utils-proxy-islands'
+                });
+            }
+        },
+        configureServer(server) {
+            registerHooksWatcher(server, async () => {
+                await updateGeneratedClientEntry();
+            }, hooksFilePath);
+            registerIslandsCssMiddleware(server, () => generatedClientEntryPath);
+            registerIslandsHmrFullReload(server, () => latestMetadata);
+        },
+        async transform(code, id) {
+            if (!hooksFilePath) {
+                return null;
+            }
+            const cleanId = id.split('?', 1)[0];
+            if (path.normalize(cleanId) !== path.normalize(hooksFilePath)) {
+                return null;
+            }
+            const metadata = await updateGeneratedClientEntry(code);
+            if (!metadata || !needsAutoWiredAssets(metadata)) {
+                return null;
+            }
+            const clientEntryExpression = config.command === 'serve' && generatedClientEntryPath
+                ? JSON.stringify(toDevFsUrl(generatedClientEntryPath))
+                : JSON.stringify(AUTO_ENTRY_PLACEHOLDER);
+            const clientStylesheetsExpression = config.command === 'serve'
+                ? JSON.stringify([DEV_ISLANDS_CSS_URL])
+                : AUTO_STYLES_PLACEHOLDER;
+            return {
+                code: injectAutoWiredIslandsConfig(code, metadata, {
+                    clientEntryExpression,
+                    clientStylesheetsExpression
+                }),
+                map: null
+            };
+        },
+        async generateBundle(_outputOptions, bundle) {
+            if (config.build.ssr || !clientEntryRef || !latestMetadata || !needsAutoWiredAssets(latestMetadata)) {
+                return;
+            }
+            const clientEntryFileName = this.getFileName(clientEntryRef);
+            const clientChunk = bundle[clientEntryFileName];
+            if (!clientChunk || clientChunk.type !== 'chunk') {
+                throw new Error('[stack-utils proxy] failed to locate the generated islands client chunk.');
+            }
+            const clientEntryUrl = toPublicAssetUrl(clientEntryFileName, config.base);
+            const clientStylesheetUrls = extractClientStylesheetUrls(clientChunk, config.base);
+            await patchServerOutputFiles(config.root, clientEntryUrl, clientStylesheetUrls);
+        }
+    };
+}
+function registerHooksWatcher(server, refreshGeneratedEntry, hooksFilePath) {
+    if (!hooksFilePath) {
+        return;
+    }
+    server.watcher.add(hooksFilePath);
+    server.watcher.on('change', (changedPath) => {
+        if (path.normalize(changedPath) !== path.normalize(hooksFilePath)) {
+            return;
+        }
+        void refreshGeneratedEntry().then(() => {
+            server.ws.send({ type: 'full-reload' });
+        });
+    });
+}
+/**
+ * Serve the combined SSR-blocking stylesheet for the islands client entry.
+ *
+ * The middleware forces the generated client entry through Vite's transform
+ * pipeline so vite-plugin-svelte populates the module graph with each
+ * component's scoped CSS module, then walks the graph and reassembles the
+ * actual CSS that those JS-wrapped style modules carry.
+ */
+function registerIslandsCssMiddleware(server, getGeneratedClientEntryPath) {
+    server.middlewares.use(DEV_ISLANDS_CSS_URL, async (req, res, next) => {
+        try {
+            const generatedClientEntryPath = getGeneratedClientEntryPath();
+            if (!generatedClientEntryPath || !existsSync(generatedClientEntryPath)) {
+                res.statusCode = 404;
+                res.end('/* no proxy islands bootstrap generated */');
+                return;
+            }
+            const css = await collectIslandsDevCss(server, generatedClientEntryPath);
+            res.setHeader('Content-Type', 'text/css; charset=utf-8');
+            res.setHeader('Cache-Control', 'no-store');
+            res.end(css);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+}
+/**
+ * Trigger a full page reload whenever a registered island component changes.
+ *
+ * The browser caches the combined stylesheet served above as a regular CSS
+ * resource, so HMR alone is not enough to flush the styles for an updated
+ * island. A full reload forces both the proxied HTML and the islands CSS to
+ * be refetched. We only react to files that are actually used by an island
+ * so editing unrelated components keeps Vite's normal HMR path.
+ */
+function registerIslandsHmrFullReload(server, getMetadata) {
+    server.watcher.on('change', (changedPath) => {
+        const metadata = getMetadata();
+        if (!metadata || metadata.components.length === 0) {
+            return;
+        }
+        const normalizedChanged = path.normalize(changedPath);
+        const componentPaths = collectComponentAbsolutePaths(metadata, server);
+        if (componentPaths.some((file) => path.normalize(file) === normalizedChanged)) {
+            server.ws.send({ type: 'full-reload' });
+        }
+    });
+}
+function collectComponentAbsolutePaths(metadata, server) {
+    const roots = new Set();
+    for (const node of server.moduleGraph.idToModuleMap.values()) {
+        if (node.file && node.file.endsWith('.svelte')) {
+            roots.add(node.file);
+        }
+    }
+    const matchedByName = new Set();
+    for (const component of metadata.components) {
+        const tail = component.source.split('/').pop() ?? component.source;
+        for (const file of roots) {
+            if (file.endsWith(`/${tail}`) || file.endsWith(`\\${tail}`)) {
+                matchedByName.add(file);
+            }
+        }
+    }
+    return [...matchedByName];
+}
+async function collectIslandsDevCss(server, generatedClientEntryPath) {
+    const url = toDevFsUrl(generatedClientEntryPath);
+    // Force the bootstrap through the client transform pipeline so each
+    // `.svelte` import's CSS counterpart is materialised in the module graph.
+    await server.transformRequest(url);
+    const bootstrapNode = await server.moduleGraph.getModuleByUrl(url, false);
+    if (!bootstrapNode) {
+        return '';
+    }
+    const cssNodes = new Set();
+    const visited = new Set();
+    const walk = (node) => {
+        if (!node || visited.has(node))
+            return;
+        visited.add(node);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const n = node;
+        const id = n.id ?? null;
+        const moduleUrl = n.url ?? null;
+        if (isCssLikeModuleId(id) || isCssLikeModuleId(moduleUrl)) {
+            cssNodes.add({ id, url: moduleUrl });
+        }
+        const imported = n.importedModules ?? [];
+        for (const child of imported) {
+            walk(child);
+        }
+    };
+    walk(bootstrapNode);
+    const chunks = [];
+    const seenCssIds = new Set();
+    for (const node of cssNodes) {
+        const requestId = node.url ?? node.id;
+        if (!requestId)
+            continue;
+        const dedupeKey = node.id ?? node.url ?? requestId;
+        if (seenCssIds.has(dedupeKey))
+            continue;
+        seenCssIds.add(dedupeKey);
+        const result = await server.transformRequest(requestId);
+        if (!result?.code)
+            continue;
+        const css = extractViteCssFromJs(result.code);
+        if (css) {
+            chunks.push(css);
+        }
+    }
+    return chunks.join('\n');
+}
+function findHooksServerFile(root) {
+    for (const extension of ['ts', 'js', 'mts', 'mjs']) {
+        const candidate = path.join(root, 'src', `hooks.server.${extension}`);
+        if (existsSync(candidate)) {
+            return path.normalize(candidate);
+        }
+    }
+    return null;
+}
+function toDevFsUrl(filePath) {
+    return `/@fs/${filePath.split(path.sep).join('/')}`;
+}
+function extractClientStylesheetUrls(chunk, base) {
+    const urls = new Set();
+    const importedCss = Array.from(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (chunk.viteMetadata?.importedCss ?? []));
+    for (const fileName of importedCss) {
+        urls.add(toPublicAssetUrl(fileName, base));
+    }
+    return [...urls];
+}
+async function patchServerOutputFiles(root, clientEntryUrl, clientStylesheetUrls) {
+    const serverOutputDirectory = path.join(root, '.svelte-kit', 'output', 'server');
+    const serverFiles = await listJavaScriptFiles(serverOutputDirectory);
+    await Promise.all(serverFiles.map(async (filePath) => {
+        const source = await readFile(filePath, 'utf8');
+        if (!source.includes(AUTO_ENTRY_PLACEHOLDER) &&
+            !source.includes(AUTO_STYLES_PLACEHOLDER)) {
+            return;
+        }
+        const patched = source
+            .replaceAll(JSON.stringify(AUTO_ENTRY_PLACEHOLDER), JSON.stringify(clientEntryUrl))
+            .replaceAll(AUTO_STYLES_PLACEHOLDER, JSON.stringify(clientStylesheetUrls));
+        await writeFile(filePath, patched, 'utf8');
+    }));
+}
+async function listJavaScriptFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listJavaScriptFiles(fullPath)));
+            continue;
+        }
+        if (entry.name.endsWith('.js')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}

package/dist/proxy/vite.d.ts

@@ -0,0 +1 @@
+export { proxyIslands } from './vite-plugin.js';

package/dist/proxy/vite.js

@@ -0,0 +1 @@
+export { proxyIslands } from './vite-plugin.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@megabudino/stack-utils",
-	"version": "1.5.0",
+	"version": "2.0.0",
 	"description": "Reusable utilities for a SvelteKit stack, including a reverse proxy and static image pipeline",
 	"type": "module",
 	"exports": {
@@ -12,6 +12,14 @@
 			"types": "./dist/proxy/index.d.ts",
 			"default": "./dist/proxy/index.js"
 		},
+		"./proxy/client": {
+			"types": "./dist/proxy/client.d.ts",
+			"default": "./dist/proxy/client.js"
+		},
+		"./proxy/vite": {
+			"types": "./dist/proxy/vite.d.ts",
+			"default": "./dist/proxy/vite.js"
+		},
 		"./images": {
 			"types": "./dist/images/index.d.ts",
 			"default": "./dist/images/index.js"

package/dist/proxy/dom-actions.d.ts

@@ -1,9 +0,0 @@
-import type { DomAction } from './types.js';
-/**
- * Apply declarative DOM actions in array order.
- *
- * Actions run after the proxy's standard HTML rewrites so selectors see the
- * final proxied markup shape, and before `textReplacements` so the legacy
- * string-based pass remains the last low-level override.
- */
-export declare function applyDomActions(html: string, actions: DomAction[]): string;

package/dist/proxy/dom-actions.js

@@ -1,54 +0,0 @@
-import { load } from 'cheerio';
-/**
- * Apply declarative DOM actions in array order.
- *
- * Actions run after the proxy's standard HTML rewrites so selectors see the
- * final proxied markup shape, and before `textReplacements` so the legacy
- * string-based pass remains the last low-level override.
- */
-export function applyDomActions(html, actions) {
-    if (actions.length === 0) {
-        return html;
-    }
-    const $ = load(html);
-    for (const action of actions) {
-        const elements = $(action.selector);
-        if (elements.length === 0) {
-            continue;
-        }
-        if (action.remove) {
-            elements.remove();
-            continue;
-        }
-        if (action.setAttributes) {
-            for (const [name, value] of Object.entries(action.setAttributes)) {
-                elements.attr(name, value);
-            }
-        }
-        if (action.removeAttributes) {
-            for (const name of action.removeAttributes) {
-                elements.removeAttr(name);
-            }
-        }
-        if (action.addClass && action.addClass.length > 0) {
-            elements.addClass(action.addClass.join(' '));
-        }
-        if (action.removeClass && action.removeClass.length > 0) {
-            elements.removeClass(action.removeClass.join(' '));
-        }
-        if (action.setText !== undefined) {
-            elements.text(action.setText);
-        }
-        if (action.setHtml !== undefined) {
-            elements.html(action.setHtml);
-        }
-        // Insertions compose with content replacement in the same action.
-        if (action.prependHtml !== undefined) {
-            elements.prepend(action.prependHtml);
-        }
-        if (action.appendHtml !== undefined) {
-            elements.append(action.appendHtml);
-        }
-    }
-    return $.html();
-}