@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

npm install @megabudino/stack-utils

Modules

proxy

A SvelteKit Handle hook that reverse-proxies unmatched routes to an origin server.

Import:

import { createProxyHandle } from '@megabudino/stack-utils/proxy';

Usage in src/hooks.server.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 | | sitemap | SitemapConfig | {} | Sitemap index injection and origin URL filtering | | proxyAssets | boolean | false | Rewrite origin asset URLs to relative paths | | additionalOrigins | string[] | [] | Additional absolute origins to rewrite like originUrl | | domActions | DomAction[] | [] | Declarative DOM transformations for proxied HTML | | textReplacements | Record<string, string> | {} | Final string replacements applied after DOM actions |

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, applies optional DOM actions, and rewrites sitemap XML 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:

import { staticImagePipeline } from '@megabudino/stack-utils/images';

Usage in vite.config.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:

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
• writes cache metadata to .stack-utils/image-variants.cache.json
• rewrites compatible <img src="/images/..."> tags to an internal StaticImage component
• keeps StaticImage internal to the package so the public API stays small

Reusing built images

If you want to build the image variants once and reuse them across machines or CI runs, commit:

static/_image-variants/
.stack-utils/image-variants.generated.json
.stack-utils/image-variants.cache.json

The pipeline will hash the current source images, verify the referenced generated files still exist, and skip regeneration when everything matches.

If you prefer generated artifacts to stay local, you can still ignore those paths in the consuming app.

Publishing Notes

The package is intended to be consumed via subpath imports:

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.