@megabudino/stack-utils 1.0.0

package/LICENSE

@@ -0,0 +1,33 @@
+Source-Available License
+
+Copyright (c) 2026 Davide Ruggeri
+All rights reserved.
+
+This software is made available in source form for inspection and limited use.
+It is not open source software.
+
+Permission is granted to any person obtaining a copy of this software and
+associated documentation files (the "Software") to:
+
+1. view, download, and inspect the source code;
+2. use the Software internally for personal, evaluation, or non-commercial use;
+3. modify the Software for internal use only.
+
+Without prior written permission from the copyright holder, you may not:
+
+1. publish, distribute, sublicense, rent, lease, or resell the Software;
+2. make the Software publicly available in source or binary form;
+3. use the Software, or derivatives of it, for commercial purposes;
+4. offer the Software as part of a hosted or managed service;
+5. remove or alter any copyright, license, or attribution notices.
+
+For commercial use, redistribution, or any other use outside the permissions
+above, contact the copyright holder for a separate license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @megabudino/stack-utils
+
+A single package with reusable utilities for a SvelteKit stack.
+
+This package is source-available. The source is provided for inspection and limited use under the terms in `LICENSE`. It is not open source.
+
+Today it exposes two modules:
+
+- `@megabudino/stack-utils/proxy`
+- `@megabudino/stack-utils/images`
+
+Module-specific docs:
+
+- `src/proxy/README.md`
+- `src/images/README.md`
+
+## Installation
+
+```bash
+npm install @megabudino/stack-utils
+```
+
+## Modules
+
+### `proxy`
+
+A SvelteKit `Handle` hook that reverse-proxies unmatched routes to an origin server.
+
+Import:
+
+```ts
+import { createProxyHandle } from '@megabudino/stack-utils/proxy';
+```
+
+Usage in `src/hooks.server.ts`:
+
+```ts
+import { createProxyHandle } from '@megabudino/stack-utils/proxy';
+
+export const handle = createProxyHandle({
+	originUrl: 'https://cms.example.com',
+	siteUrl: 'https://www.example.com'
+});
+```
+
+Proxy config:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `originUrl` | `string` | required | Origin server URL |
+| `siteUrl` | `string` | required | Public site URL |
+| `sitemaps` | `string[]` | `[]` | SvelteKit sitemap URLs to inject into sitemap indexes |
+| `sitemapCacheSeconds` | `number` | `3600` | Cache max-age for sitemap responses |
+| `proxyAssets` | `boolean` | `false` | Rewrite origin asset URLs to relative paths |
+| `additionalOrigins` | `string[]` | `[]` | Additional absolute origins to rewrite like `originUrl` |
+
+What it does:
+
+- lets SvelteKit routes resolve normally when a route exists
+- proxies unmatched requests to the configured origin
+- rewrites redirects back to the public domain
+- rewrites HTML and injects extra sitemap entries when configured
+
+### `images`
+
+A static image pipeline for Svelte projects that keep source assets in `static/images` and want responsive variants plus automatic `<img>` upgrades.
+
+Import:
+
+```ts
+import { staticImagePipeline } from '@megabudino/stack-utils/images';
+```
+
+Usage in `vite.config.ts`:
+
+```ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import { staticImagePipeline } from '@megabudino/stack-utils/images';
+
+export default defineConfig({
+	plugins: [sveltekit(), staticImagePipeline()]
+});
+```
+
+The `images` module also exports:
+
+```ts
+import {
+	generateStaticImageVariants,
+	staticImagePipelineConfig
+} from '@megabudino/stack-utils/images';
+```
+
+What it does:
+
+- reads source images from `static/images`
+- writes responsive variants to `static/_image-variants`
+- writes its generated manifest to `.stack-utils/image-variants.generated.json`
+- rewrites compatible `<img src="/images/...">` tags to an internal `StaticImage` component
+- keeps `StaticImage` internal to the package so the public API stays small
+
+### Consumer gitignore
+
+In the consuming app, ignore the generated pipeline output:
+
+```gitignore
+static/_image-variants
+.stack-utils
+```
+
+## Publishing Notes
+
+The package is intended to be consumed via subpath imports:
+
+```ts
+import { createProxyHandle } from '@megabudino/stack-utils/proxy';
+import { staticImagePipeline } from '@megabudino/stack-utils/images';
+```
+
+`StaticImage.svelte` is not part of the documented public API even though the package resolves it internally for the image pipeline.
+
+## License
+
+Source-available. See [LICENSE](./LICENSE).

package/dist/images/class-split.d.ts

@@ -0,0 +1,6 @@
+export interface SplitClassNames {
+    wrapperClass: string;
+    imageClass: string;
+}
+export declare function splitStaticImageClasses(classValue: string): SplitClassNames;
+export declare function joinClassNames(...values: Array<string | undefined>): string;

package/dist/images/class-split.js

@@ -0,0 +1,49 @@
+const WRAPPER_CLASS_PATTERNS = [
+    /^row-span-/,
+    /^col-span-/,
+    /^row-start-/,
+    /^row-end-/,
+    /^col-start-/,
+    /^col-end-/,
+    /^order-/,
+    /^self-/,
+    /^justify-self-/,
+    /^place-self-/,
+    /^aspect-/
+];
+const IMAGE_CLASS_PATTERNS = [
+    /^rounded(?:-|$)/,
+    /^object(?:-|$)/,
+    /^shadow(?:-|$)/,
+    /^ring(?:-|$)/,
+    /^opacity(?:-|$)/,
+    /^mix-blend-/,
+    /^filter$/,
+    /^blur(?:-|$)/
+];
+export function splitStaticImageClasses(classValue) {
+    const wrapperTokens = [];
+    const imageTokens = [];
+    for (const token of classValue.split(/\s+/).filter(Boolean)) {
+        const utilityName = getUtilityName(token);
+        if (WRAPPER_CLASS_PATTERNS.some((pattern) => pattern.test(utilityName))) {
+            wrapperTokens.push(token);
+            continue;
+        }
+        if (IMAGE_CLASS_PATTERNS.some((pattern) => pattern.test(utilityName))) {
+            imageTokens.push(token);
+            continue;
+        }
+        imageTokens.push(token);
+    }
+    return {
+        wrapperClass: wrapperTokens.join(' '),
+        imageClass: imageTokens.join(' ')
+    };
+}
+export function joinClassNames(...values) {
+    return values.filter(Boolean).join(' ');
+}
+function getUtilityName(classToken) {
+    return classToken.split(':').pop() ?? classToken;
+}

package/dist/images/config.d.ts

@@ -0,0 +1,16 @@
+export declare const staticImagePipelineConfig: {
+    readonly sourceDirectory: "static/images";
+    readonly outputDirectory: "static/_image-variants";
+    readonly publicSourcePrefix: "/images";
+    readonly publicOutputPrefix: "/_image-variants";
+    readonly manifestPath: ".stack-utils/image-variants.generated.json";
+    readonly supportedExtensions: readonly [".jpg", ".jpeg", ".png", ".webp"];
+    readonly widths: readonly [320, 480, 640, 768, 960, 1280, 1536, 1920];
+    readonly quality: {
+        readonly avif: 50;
+        readonly webp: 75;
+        readonly jpeg: 82;
+        readonly png: 80;
+    };
+};
+export type StaticImageExtension = (typeof staticImagePipelineConfig.supportedExtensions)[number];

package/dist/images/config.js

@@ -0,0 +1,15 @@
+export const staticImagePipelineConfig = {
+    sourceDirectory: 'static/images',
+    outputDirectory: 'static/_image-variants',
+    publicSourcePrefix: '/images',
+    publicOutputPrefix: '/_image-variants',
+    manifestPath: '.stack-utils/image-variants.generated.json',
+    supportedExtensions: ['.jpg', '.jpeg', '.png', '.webp'],
+    widths: [320, 480, 640, 768, 960, 1280, 1536, 1920],
+    quality: {
+        avif: 50,
+        webp: 75,
+        jpeg: 82,
+        png: 80
+    }
+};

package/dist/images/generator.d.ts

@@ -0,0 +1,7 @@
+import type { ImageVariantManifest } from './types.js';
+interface GenerateStaticImageVariantsOptions {
+    root: string;
+    log?: (message: string) => void;
+}
+export declare function generateStaticImageVariants({ root, log }: GenerateStaticImageVariantsOptions): Promise<ImageVariantManifest>;
+export {};

package/dist/images/generator.js

@@ -0,0 +1,203 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { staticImagePipelineConfig } from './config.js';
+const SUPPORTED_EXTENSIONS = new Set(staticImagePipelineConfig.supportedExtensions);
+export async function generateStaticImageVariants({ root, log = () => undefined }) {
+    const sourceDirectory = path.join(root, staticImagePipelineConfig.sourceDirectory);
+    const outputDirectory = path.join(root, staticImagePipelineConfig.outputDirectory);
+    const manifestPath = path.join(root, staticImagePipelineConfig.manifestPath);
+    await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    const sourceFiles = await collectSourceImages(sourceDirectory);
+    if (sourceFiles.length === 0) {
+        await fs.mkdir(outputDirectory, { recursive: true });
+        await fs.writeFile(manifestPath, '{}\n');
+        return {};
+    }
+    await fs.mkdir(outputDirectory, { recursive: true });
+    const manifest = {};
+    for (const file of sourceFiles) {
+        const entry = await generateManifestEntry({ file, outputDirectory });
+        if (entry) {
+            manifest[entry.src] = entry;
+        }
+    }
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    log(`[static-image-pipeline] generated ${Object.keys(manifest).length} manifest entries`);
+    return manifest;
+}
+async function generateManifestEntry({ file, outputDirectory }) {
+    const image = sharp(file.absolutePath, { failOn: 'none' });
+    const metadata = await image.metadata();
+    if (!metadata.width || !metadata.height) {
+        return null;
+    }
+    const relativePath = toPosixPath(file.relativePath);
+    const sourcePath = `${staticImagePipelineConfig.publicSourcePrefix}/${relativePath}`;
+    const fallbackExtension = getFallbackExtension(path.extname(relativePath));
+    const widths = getTargetWidths(metadata.width);
+    const outputSubdirectory = path.join(outputDirectory, path.dirname(file.relativePath));
+    const basename = path.parse(file.relativePath).name;
+    await fs.mkdir(outputSubdirectory, { recursive: true });
+    const formats = {
+        avif: [],
+        webp: [],
+        fallback: []
+    };
+    for (const width of widths) {
+        const height = Math.round((metadata.height * width) / metadata.width);
+        formats.avif.push(await generateVariant({
+            sourceFile: file,
+            outputSubdirectory,
+            relativePath,
+            basename,
+            width,
+            height,
+            format: 'avif',
+            fallbackExtension
+        }));
+        formats.webp.push(await generateVariant({
+            sourceFile: file,
+            outputSubdirectory,
+            relativePath,
+            basename,
+            width,
+            height,
+            format: 'webp',
+            fallbackExtension
+        }));
+        formats.fallback.push(await generateVariant({
+            sourceFile: file,
+            outputSubdirectory,
+            relativePath,
+            basename,
+            width,
+            height,
+            format: 'fallback',
+            fallbackExtension
+        }));
+    }
+    return {
+        src: sourcePath,
+        width: metadata.width,
+        height: metadata.height,
+        fallbackExtension,
+        formats
+    };
+}
+async function generateVariant({ sourceFile, outputSubdirectory, relativePath, basename, width, height, format, fallbackExtension }) {
+    const extension = getGeneratedExtension(format, fallbackExtension);
+    const outputFilename = `${basename}-${width}.${extension}`;
+    const outputAbsolutePath = path.join(outputSubdirectory, outputFilename);
+    const outputRelativeDirectory = path.dirname(relativePath);
+    const outputRelativePath = outputRelativeDirectory === '.'
+        ? outputFilename
+        : `${toPosixPath(outputRelativeDirectory)}/${outputFilename}`;
+    const shouldWriteVariant = await needsWrite(outputAbsolutePath, sourceFile.mtimeMs);
+    if (shouldWriteVariant) {
+        let pipeline = sharp(sourceFile.absolutePath, { failOn: 'none' }).resize({
+            width,
+            withoutEnlargement: true
+        });
+        if (format === 'avif') {
+            pipeline = pipeline.avif({ quality: staticImagePipelineConfig.quality.avif });
+        }
+        else if (format === 'webp') {
+            pipeline = pipeline.webp({ quality: staticImagePipelineConfig.quality.webp });
+        }
+        else if (fallbackExtension === 'png') {
+            pipeline = pipeline.png({
+                quality: staticImagePipelineConfig.quality.png,
+                compressionLevel: 9,
+                palette: true
+            });
+        }
+        else if (fallbackExtension === 'webp') {
+            pipeline = pipeline.webp({ quality: staticImagePipelineConfig.quality.webp });
+        }
+        else {
+            pipeline = pipeline.jpeg({
+                quality: staticImagePipelineConfig.quality.jpeg,
+                mozjpeg: true
+            });
+        }
+        await pipeline.toFile(outputAbsolutePath);
+    }
+    return {
+        width,
+        height,
+        url: `${staticImagePipelineConfig.publicOutputPrefix}/${outputRelativePath}`
+    };
+}
+async function collectSourceImages(directory) {
+    const files = [];
+    await walkDirectory(directory, async (absolutePath, relativePath) => {
+        const extension = path.extname(absolutePath).toLowerCase();
+        if (!SUPPORTED_EXTENSIONS.has(extension)) {
+            return;
+        }
+        const stats = await fs.stat(absolutePath);
+        files.push({
+            absolutePath,
+            relativePath,
+            mtimeMs: stats.mtimeMs
+        });
+    });
+    files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    return files;
+}
+async function walkDirectory(directory, onFile, baseDirectory = directory) {
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    for (const entry of entries) {
+        const absolutePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            await walkDirectory(absolutePath, onFile, baseDirectory);
+            continue;
+        }
+        const relativePath = path.relative(baseDirectory, absolutePath);
+        await onFile(absolutePath, relativePath);
+    }
+}
+async function needsWrite(outputPath, sourceMtimeMs) {
+    try {
+        const outputStats = await fs.stat(outputPath);
+        return outputStats.mtimeMs < sourceMtimeMs;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return true;
+        }
+        throw error;
+    }
+}
+function getTargetWidths(originalWidth) {
+    const widths = staticImagePipelineConfig.widths.filter((width) => width < originalWidth).map(Number);
+    return Array.from(new Set([...widths, originalWidth])).sort((left, right) => left - right);
+}
+function getFallbackExtension(extension) {
+    if (extension === '.png') {
+        return 'png';
+    }
+    if (extension === '.webp') {
+        return 'webp';
+    }
+    return 'jpg';
+}
+function getGeneratedExtension(format, fallbackExtension) {
+    if (format === 'fallback') {
+        return fallbackExtension;
+    }
+    return format;
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join('/');
+}

package/dist/images/index.d.ts

@@ -0,0 +1,4 @@
+export { staticImagePipeline } from './vite-plugin.js';
+export { generateStaticImageVariants } from './generator.js';
+export { staticImagePipelineConfig } from './config.js';
+export type { GeneratedImageFormat, ImageVariant, ImageVariantManifest, ImageVariantManifestEntry } from './types.js';

package/dist/images/index.js

@@ -0,0 +1,3 @@
+export { staticImagePipeline } from './vite-plugin.js';
+export { generateStaticImageVariants } from './generator.js';
+export { staticImagePipelineConfig } from './config.js';

package/dist/images/internal/StaticImage.svelte

@@ -0,0 +1,76 @@
+<script lang="ts">
+	import type { HTMLImgAttributes } from 'svelte/elements';
+
+	import { joinClassNames } from '../class-split';
+	import type { ImageVariant, ImageVariantManifest } from '../types';
+
+	type StaticImageProps = Omit<HTMLImgAttributes, 'src' | 'class'> & {
+		src: string;
+		manifest?: ImageVariantManifest;
+		optimize?: boolean;
+		wrapperClass?: string;
+		imgClass?: string;
+		class?: string;
+	};
+
+	let {
+		src,
+		manifest = {},
+		alt = '',
+		optimize = true,
+		sizes,
+		srcset,
+		width,
+		height,
+		wrapperClass = '',
+		imgClass = '',
+		class: className = '',
+		...restProps
+	}: StaticImageProps = $props();
+
+	const manifestEntry = $derived(optimize && !srcset ? manifest[src] : undefined);
+	const fallbackVariants = $derived(manifestEntry?.formats.fallback ?? []);
+	const avifSrcset = $derived(toSrcset(manifestEntry?.formats.avif));
+	const webpSrcset = $derived(toSrcset(manifestEntry?.formats.webp));
+	const fallbackSrcset = $derived(toSrcset(fallbackVariants));
+	const fallbackSrc = $derived(getLargestVariant(fallbackVariants)?.url ?? src);
+	const resolvedWidth = $derived(width ?? manifestEntry?.width);
+	const resolvedHeight = $derived(height ?? manifestEntry?.height);
+	const resolvedImgClass = $derived(joinClassNames(className, imgClass));
+	const fallbackClass = $derived(joinClassNames(wrapperClass, resolvedImgClass));
+
+	function toSrcset(variants: ImageVariant[] | undefined) {
+		if (!variants?.length) {
+			return undefined;
+		}
+
+		return variants.map((variant) => `${variant.url} ${variant.width}w`).join(', ');
+	}
+
+	function getLargestVariant(variants: ImageVariant[]) {
+		return variants[variants.length - 1];
+	}
+</script>
+
+{#if manifestEntry}
+	<picture class={wrapperClass || undefined}>
+		{#if avifSrcset}
+			<source type="image/avif" srcset={avifSrcset} sizes={sizes} />
+		{/if}
+		{#if webpSrcset}
+			<source type="image/webp" srcset={webpSrcset} sizes={sizes} />
+		{/if}
+		<img
+			{...restProps}
+			src={fallbackSrc}
+			alt={alt}
+			srcset={fallbackSrcset}
+			sizes={sizes}
+			width={resolvedWidth}
+			height={resolvedHeight}
+			class={resolvedImgClass || undefined}
+		/>
+	</picture>
+{:else}
+	<img {...restProps} {src} {alt} {srcset} {sizes} {width} {height} class={fallbackClass || undefined} />
+{/if}

package/dist/images/types.d.ts

@@ -0,0 +1,14 @@
+export type GeneratedImageFormat = 'avif' | 'webp' | 'fallback';
+export interface ImageVariant {
+    width: number;
+    height: number;
+    url: string;
+}
+export interface ImageVariantManifestEntry {
+    src: string;
+    width: number;
+    height: number;
+    fallbackExtension: 'jpg' | 'png' | 'webp';
+    formats: Record<GeneratedImageFormat, ImageVariant[]>;
+}
+export type ImageVariantManifest = Record<string, ImageVariantManifestEntry>;

package/dist/images/types.js

@@ -0,0 +1 @@
+export {};

package/dist/images/vite-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function staticImagePipeline(): Plugin;

package/dist/images/vite-plugin.js

@@ -0,0 +1,254 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { parse } from 'svelte/compiler';
+import { joinClassNames, splitStaticImageClasses } from './class-split.js';
+import { staticImagePipelineConfig } from './config.js';
+import { generateStaticImageVariants } from './generator.js';
+const PACKAGE_NAME = '@megabudino/stack-utils';
+const VIRTUAL_MANIFEST_MODULE = 'virtual:stack-utils-image-manifest';
+const RESOLVED_VIRTUAL_MANIFEST_MODULE = '\0virtual:stack-utils-image-manifest';
+const STATIC_IMAGE_IMPORT_BLOCK = [
+    `import StaticImage from '${PACKAGE_NAME}/images/internal/StaticImage.svelte';`,
+    `import staticImagePipelineManifest from '${VIRTUAL_MANIFEST_MODULE}';`
+].join('\n');
+const OPTIMIZABLE_SOURCE_REGEX = /^\/images\/.+\.(?:png|jpe?g|webp)$/i;
+export function staticImagePipeline() {
+    let config;
+    let generationPromise = null;
+    const ensureGenerated = () => {
+        if (generationPromise) {
+            return generationPromise;
+        }
+        generationPromise = generateStaticImageVariants({
+            root: config.root,
+            log: (message) => config.logger.info(message)
+        })
+            .then(() => undefined)
+            .finally(() => {
+            generationPromise = null;
+        });
+        return generationPromise;
+    };
+    return {
+        name: 'static-image-pipeline',
+        enforce: 'pre',
+        configResolved(resolvedConfig) {
+            config = resolvedConfig;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_MANIFEST_MODULE) {
+                return RESOLVED_VIRTUAL_MANIFEST_MODULE;
+            }
+            return null;
+        },
+        async load(id) {
+            if (id !== RESOLVED_VIRTUAL_MANIFEST_MODULE) {
+                return null;
+            }
+            const manifest = await readManifest(config.root);
+            return `export default ${manifest};`;
+        },
+        async buildStart() {
+            await ensureGenerated();
+        },
+        configureServer(server) {
+            registerStaticImageWatcher(server, ensureGenerated, config.root);
+        },
+        transform(code, id) {
+            const cleanId = id.split('?', 1)[0];
+            if (!cleanId.endsWith('.svelte') || isInternalStaticImageFile(cleanId)) {
+                return null;
+            }
+            return rewriteStaticImages(code);
+        }
+    };
+}
+function isInternalStaticImageFile(filePath) {
+    return (filePath.includes('/src/images/internal/') ||
+        filePath.includes('/dist/images/internal/') ||
+        filePath.includes('/node_modules/@megabudino/stack-utils/dist/images/internal/'));
+}
+function registerStaticImageWatcher(server, ensureGenerated, root) {
+    const watchedDirectory = path.join(root, staticImagePipelineConfig.sourceDirectory);
+    server.watcher.add(watchedDirectory);
+    const maybeRegenerate = (changedPath) => {
+        const normalizedPath = path.normalize(changedPath);
+        const normalizedDirectory = path.normalize(watchedDirectory);
+        if (!normalizedPath.startsWith(normalizedDirectory)) {
+            return;
+        }
+        if (!OPTIMIZABLE_SOURCE_REGEX.test(toPublicSourcePath(normalizedDirectory, normalizedPath))) {
+            return;
+        }
+        void ensureGenerated().then(() => {
+            server.ws.send({ type: 'full-reload' });
+        });
+    };
+    server.watcher.on('add', maybeRegenerate);
+    server.watcher.on('change', maybeRegenerate);
+    server.watcher.on('unlink', maybeRegenerate);
+}
+function rewriteStaticImages(code) {
+    if (!code.includes('<img')) {
+        return null;
+    }
+    const ast = parse(code);
+    const imgNodes = collectOptimizableImgNodes(ast.html);
+    if (imgNodes.length === 0) {
+        return null;
+    }
+    let transformedCode = code;
+    for (const node of [...imgNodes].sort((left, right) => right.start - left.start)) {
+        const originalMarkup = transformedCode.slice(node.start, node.end);
+        const replacement = convertImgToComponentMarkup(node, originalMarkup);
+        transformedCode =
+            transformedCode.slice(0, node.start) + replacement + transformedCode.slice(node.end);
+    }
+    if (!transformedCode.includes(STATIC_IMAGE_IMPORT_BLOCK)) {
+        transformedCode = injectStaticImageImport(transformedCode, ast.instance);
+    }
+    return {
+        code: transformedCode,
+        map: null
+    };
+}
+function collectOptimizableImgNodes(rootNode) {
+    const result = [];
+    visitNode(rootNode, false, result);
+    return result;
+}
+function visitNode(node, insidePicture, result) {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+    const nodeIsElement = node.type === 'Element';
+    const nextInsidePicture = insidePicture || (nodeIsElement && node.name === 'picture');
+    if (nodeIsElement && node.name === 'img' && !insidePicture && isOptimizableImgNode(node)) {
+        result.push(node);
+    }
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (child && typeof child === 'object' && 'type' in child) {
+                    visitNode(child, nextInsidePicture, result);
+                }
+            }
+            continue;
+        }
+        if (value && typeof value === 'object' && 'type' in value) {
+            visitNode(value, nextInsidePicture, result);
+        }
+    }
+}
+function isOptimizableImgNode(node) {
+    const attributes = node.attributes ?? [];
+    const sourceAttribute = attributes.find((attribute) => attribute.type === 'Attribute' && attribute.name === 'src');
+    if (!sourceAttribute) {
+        return false;
+    }
+    const sourceValue = readStaticAttributeValue(sourceAttribute);
+    if (!sourceValue || !OPTIMIZABLE_SOURCE_REGEX.test(sourceValue)) {
+        return false;
+    }
+    if (attributes.some((attribute) => attribute.type === 'Attribute' && attribute.name === 'srcset')) {
+        return false;
+    }
+    if (attributes.some((attribute) => attribute.type === 'Attribute' && attribute.name === 'data-no-optimize')) {
+        return false;
+    }
+    if (attributes.some((attribute) => attribute.type === 'Binding')) {
+        return false;
+    }
+    return true;
+}
+function readStaticAttributeValue(attribute) {
+    if (attribute.value === true || !Array.isArray(attribute.value) || attribute.value.length !== 1) {
+        return null;
+    }
+    const [value] = attribute.value;
+    return value?.type === 'Text' ? value.data : null;
+}
+function convertImgToComponentMarkup(node, markup) {
+    const classAttribute = findAttribute(node, 'class');
+    const wrapperOverrideAttribute = findAttribute(node, 'data-static-image-wrapper-class');
+    const imageOverrideAttribute = findAttribute(node, 'data-static-image-img-class');
+    const classValue = classAttribute ? readStaticAttributeValue(classAttribute) : null;
+    const wrapperOverride = wrapperOverrideAttribute
+        ? readStaticAttributeValue(wrapperOverrideAttribute)
+        : null;
+    const imageOverride = imageOverrideAttribute
+        ? readStaticAttributeValue(imageOverrideAttribute)
+        : null;
+    const removedAttributes = [
+        ...(classValue ? [classAttribute] : []),
+        ...(wrapperOverride ? [wrapperOverrideAttribute] : []),
+        ...(imageOverride ? [imageOverrideAttribute] : [])
+    ].filter(Boolean);
+    let rewritten = stripAttributes(markup, node.start, removedAttributes).replace(/^<img\b/, '<StaticImage manifest={staticImagePipelineManifest}');
+    const splitClassNames = classValue
+        ? splitStaticImageClasses(classValue)
+        : { wrapperClass: '', imageClass: '' };
+    const wrapperClass = joinClassNames(splitClassNames.wrapperClass, wrapperOverride ?? undefined);
+    const imageClass = joinClassNames(splitClassNames.imageClass, imageOverride ?? undefined);
+    const extraAttributes = [
+        wrapperClass ? `wrapperClass="${escapeAttributeValue(wrapperClass)}"` : '',
+        imageClass ? `class="${escapeAttributeValue(imageClass)}"` : ''
+    ].filter(Boolean);
+    if (extraAttributes.length === 0) {
+        return ensureSelfClosingTag(rewritten);
+    }
+    return appendAttributes(rewritten, extraAttributes);
+}
+function injectStaticImageImport(code, instanceScript) {
+    if (!instanceScript) {
+        return `<script>\n${STATIC_IMAGE_IMPORT_BLOCK}\n</script>\n\n${code}`;
+    }
+    const importNodes = instanceScript.content.body.filter((node) => node.type === 'ImportDeclaration');
+    const insertPosition = importNodes.length > 0 ? importNodes[importNodes.length - 1].end : instanceScript.content.start;
+    return `${code.slice(0, insertPosition)}\n${STATIC_IMAGE_IMPORT_BLOCK}${code.slice(insertPosition)}`;
+}
+function findAttribute(node, name) {
+    return node.attributes?.find((attribute) => attribute.type === 'Attribute' && attribute.name === name);
+}
+function stripAttributes(markup, nodeStart, attributes) {
+    let rewritten = markup;
+    for (const attribute of [...attributes].sort((left, right) => right.start - left.start)) {
+        const localStart = attribute.start - nodeStart;
+        const localEnd = attribute.end - nodeStart;
+        rewritten = rewritten.slice(0, localStart) + rewritten.slice(localEnd);
+    }
+    return rewritten;
+}
+function appendAttributes(markup, attributes) {
+    const normalizedMarkup = ensureSelfClosingTag(markup);
+    const attributeString = attributes.join(' ');
+    return normalizedMarkup.replace(/\s*\/>$/, ` ${attributeString} />`);
+}
+function ensureSelfClosingTag(markup) {
+    if (markup.endsWith('/>')) {
+        return markup;
+    }
+    if (markup.endsWith('>')) {
+        return `${markup.slice(0, -1)} />`;
+    }
+    return markup;
+}
+function escapeAttributeValue(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
+function toPublicSourcePath(sourceDirectory, absolutePath) {
+    const relativePath = path.relative(sourceDirectory, absolutePath).split(path.sep).join('/');
+    return `${staticImagePipelineConfig.publicSourcePrefix}/${relativePath}`;
+}
+async function readManifest(root) {
+    const manifestPath = path.join(root, staticImagePipelineConfig.manifestPath);
+    try {
+        return await fs.readFile(manifestPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return '{}';
+        }
+        throw error;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './proxy/index.js';
+export * from './images/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './proxy/index.js';
+export * from './images/index.js';

package/dist/proxy/handle.d.ts

@@ -0,0 +1,9 @@
+import type { Handle } from '@sveltejs/kit';
+import type { ProxyConfig } from './types.js';
+/**
+ * Create a SvelteKit `Handle` hook that reverse-proxies requests to an origin.
+ *
+ * Routes matched by SvelteKit's file-based router are resolved locally;
+ * everything else is forwarded to the origin.
+ */
+export declare function createProxyHandle(config: ProxyConfig): Handle;

package/dist/proxy/handle.js

@@ -0,0 +1,90 @@
+import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
+/**
+ * Create a SvelteKit `Handle` hook that reverse-proxies requests to an origin.
+ *
+ * Routes matched by SvelteKit's file-based router are resolved locally;
+ * everything else is forwarded to the origin.
+ */
+export function createProxyHandle(config) {
+    const { originUrl, siteUrl } = config;
+    const sitemaps = config.sitemaps ?? [];
+    const sitemapCache = `public, max-age=${config.sitemapCacheSeconds ?? 3600}`;
+    const proxyAssets = config.proxyAssets ?? false;
+    const additionalOrigins = config.additionalOrigins ?? [];
+    return async ({ event, resolve }) => {
+        const { pathname, search } = event.url;
+        if (event.route.id) {
+            return resolve(event);
+        }
+        const upstream = new URL(pathname + search, originUrl);
+        const headers = new Headers(event.request.headers);
+        headers.delete('accept-encoding');
+        headers.delete('host');
+        headers.delete('content-length');
+        let upstreamResponse;
+        try {
+            upstreamResponse = await fetch(upstream, {
+                method: event.request.method,
+                headers,
+                redirect: 'manual',
+                body: event.request.method === 'GET' || event.request.method === 'HEAD'
+                    ? undefined
+                    : event.request.body
+            });
+        }
+        catch {
+            return new Response('Bad Gateway', { status: 502 });
+        }
+        if (upstreamResponse.status >= 300 && upstreamResponse.status < 400) {
+            const location = upstreamResponse.headers.get('location');
+            if (location) {
+                try {
+                    const nextUrl = new URL(location);
+                    return new Response(null, {
+                        status: upstreamResponse.status,
+                        headers: {
+                            location: `${siteUrl}${nextUrl.pathname}${nextUrl.search}`
+                        }
+                    });
+                }
+                catch {
+                    return new Response(null, {
+                        status: upstreamResponse.status,
+                        headers: { location }
+                    });
+                }
+            }
+        }
+        const cleanHeaders = new Headers(upstreamResponse.headers);
+        cleanHeaders.delete('content-encoding');
+        cleanHeaders.delete('content-length');
+        cleanHeaders.delete('transfer-encoding');
+        const contentType = upstreamResponse.headers.get('content-type') ?? '';
+        if (contentType.includes('text/xml') || contentType.includes('application/xml')) {
+            let xml = await upstreamResponse.text();
+            xml = xml.replace(/<\?xml-stylesheet[^?]*\?>\s*/g, '');
+            if (sitemaps.length > 0 && xml.includes('</sitemapindex>')) {
+                xml = injectIntoSitemapIndex(xml, siteUrl, sitemaps);
+            }
+            cleanHeaders.set('cache-control', sitemapCache);
+            return new Response(xml, {
+                status: upstreamResponse.status,
+                statusText: upstreamResponse.statusText,
+                headers: cleanHeaders
+            });
+        }
+        if (contentType.includes('text/html')) {
+            const html = await upstreamResponse.text();
+            return new Response(rewriteHtml(html, originUrl, siteUrl, proxyAssets, additionalOrigins), {
+                status: upstreamResponse.status,
+                statusText: upstreamResponse.statusText,
+                headers: cleanHeaders
+            });
+        }
+        return new Response(upstreamResponse.body, {
+            status: upstreamResponse.status,
+            statusText: upstreamResponse.statusText,
+            headers: cleanHeaders
+        });
+    };
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,2 @@
+export { createProxyHandle } from './handle.js';
+export type { ProxyConfig } from './types.js';

package/dist/proxy/index.js

@@ -0,0 +1 @@
+export { createProxyHandle } from './handle.js';

package/dist/proxy/rewrite.d.ts

@@ -0,0 +1,13 @@
+/**
+ * HTML / XML rewriting utilities for the reverse proxy.
+ */
+/**
+ * Rewrite HTML returned by the origin so it works under the public domain.
+ *
+ * - Absolute links pointing to the public domain -> relative paths.
+ * - When `proxyAssets` is true, absolute origin URLs are stripped to relative paths.
+ * - When `proxyAssets` is false, absolute origin URLs are left as-is.
+ */
+export declare function rewriteHtml(html: string, originUrl: string, siteUrl: string, proxyAssets?: boolean, additionalOrigins?: string[]): string;
+/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
+export declare function injectIntoSitemapIndex(xml: string, siteUrl: string, sitemaps: string[]): string;

package/dist/proxy/rewrite.js

@@ -0,0 +1,50 @@
+/**
+ * HTML / XML rewriting utilities for the reverse proxy.
+ */
+/** Build a domain-matching regex from a public site URL. */
+function domainPattern(siteUrl) {
+    const { hostname } = new URL(siteUrl);
+    // Strip leading "www." so we match both variants
+    const bare = hostname.replace(/^www\./, '');
+    const escaped = bare.replace(/\./g, '\\.');
+    return new RegExp(`href=["']https?://(www\\.)?${escaped}([^"']*)["']`, 'gi');
+}
+/**
+ * Build a regex that matches absolute URLs for a given origin,
+ * capturing the path portion (everything after the origin).
+ */
+function originPattern(origin) {
+    const escaped = origin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(escaped, 'gi');
+}
+/**
+ * Rewrite HTML returned by the origin so it works under the public domain.
+ *
+ * - Absolute links pointing to the public domain -> relative paths.
+ * - When `proxyAssets` is true, absolute origin URLs are stripped to relative paths.
+ * - When `proxyAssets` is false, absolute origin URLs are left as-is.
+ */
+export function rewriteHtml(html, originUrl, siteUrl, proxyAssets = false, additionalOrigins = []) {
+    html = html.replace(domainPattern(siteUrl), 'href="$2"');
+    html = html.replace(/(<link[^>]*rel=["']canonical["'][^>]*href=["'])([^"']*)["']/gi, (_, prefix, value) => {
+        try {
+            value = new URL(value).pathname;
+        }
+        catch { }
+        return `${prefix}${siteUrl}${value}"`;
+    });
+    if (proxyAssets) {
+        const origins = [originUrl, ...additionalOrigins];
+        for (const origin of origins) {
+            html = html.replace(originPattern(origin), '');
+        }
+    }
+    return html;
+}
+/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
+export function injectIntoSitemapIndex(xml, siteUrl, sitemaps) {
+    const entries = sitemaps
+        .map((url) => `\t<sitemap>\n\t\t<loc>${siteUrl}${url}</loc>\n\t</sitemap>`)
+        .join('\n');
+    return xml.replace('</sitemapindex>', `${entries}\n</sitemapindex>`);
+}

package/dist/proxy/types.d.ts

@@ -0,0 +1,28 @@
+/** Configuration for the reverse proxy. */
+export interface ProxyConfig {
+    /** The origin URL (not publicly exposed). */
+    originUrl: string;
+    /** The public site URL (used in sitemaps and link rewriting). */
+    siteUrl: string;
+    /**
+     * SvelteKit sitemap URLs to inject into the origin's sitemap index.
+     * Defaults to `[]`.
+     */
+    sitemaps?: string[];
+    /**
+     * Cache-Control max-age (in seconds) for sitemap responses.
+     * Defaults to 3600 (1 hour).
+     */
+    sitemapCacheSeconds?: number;
+    /**
+     * If true, absolute origin URLs in HTML are rewritten to relative paths
+     * so assets are served through the SvelteKit proxy and the origin is never exposed.
+     * Defaults to false (absolute origin URLs are left as-is).
+     */
+    proxyAssets?: boolean;
+    /**
+     * Additional origin URLs whose absolute references in HTML should be
+     * rewritten the same way as `originUrl` (e.g. legacy/migration domains).
+     */
+    additionalOrigins?: string[];
+}

package/dist/proxy/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@megabudino/stack-utils",
+	"version": "1.0.0",
+	"description": "Reusable utilities for a SvelteKit stack, including a reverse proxy and static image pipeline",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./proxy": {
+			"types": "./dist/proxy/index.d.ts",
+			"default": "./dist/proxy/index.js"
+		},
+		"./images": {
+			"types": "./dist/images/index.d.ts",
+			"default": "./dist/images/index.js"
+		},
+		"./images/internal/StaticImage.svelte": {
+			"svelte": "./dist/images/internal/StaticImage.svelte",
+			"default": "./dist/images/internal/StaticImage.svelte"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "node ./scripts/build.mjs",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"sharp": "^0.34.5"
+	},
+	"peerDependencies": {
+		"@sveltejs/kit": "^2.0.0",
+		"svelte": "^5.0.0",
+		"vite": "^7.0.0 || ^8.0.0"
+	},
+	"devDependencies": {
+		"@sveltejs/kit": "^2.0.0",
+		"@types/node": "^24.12.0",
+		"svelte": "^5.54.0",
+		"typescript": "^5.0.0",
+		"vite": "^8.0.1"
+	},
+	"license": "SEE LICENSE IN LICENSE"
+}