add doc about wisp skipping same CID during upload and note about sveltekit/vite chunking #8

docs: add blob reuse & framework caveats guide

Documents the SvelteKit version hash issue that breaks Wisp's blob reuse by forcing re-upload of unchanged chunks on every deploy. Includes the fixed-version workaround and notes the tradeoff with SvelteKit's built-in cache busting.

Refs #37

+36

2 changed files

Diff round #0

expand all

docs

astro.config.mjs

src

content

docs

guides

blob-reuse.md

docs/astro.config.mjs

··· 31 31 { label: 'Self-Hosting', slug: 'deployment' }, 32 32 { label: 'Monitoring & Metrics', slug: 'monitoring' }, 33 33 { label: 'Redirects & Rewrites', slug: 'redirects' }, 34 + { label: 'Blob Reuse & Framework Caveats', slug: 'guides/blob-reuse' }, 34 35 ], 35 36 }, 36 37 {

+35

docs/src/content/docs/guides/blob-reuse.md

··· 1 + --- 2 + title: Blob Reuse & Framework Caveats 3 + description: How Wisp's blob reuse works and how to avoid breaking it with framework defaults 4 + --- 5 + 6 + Wisp uses content-addressed blob storage — when you deploy, blobs that haven't changed are skipped. This means only new or modified files get uploaded, making subsequent deployments fast and cheap. 7 + 8 + However, some frameworks include build-time hashes or version identifiers that change on every build, which causes all dependent chunks to be re-uploaded even when their actual content hasn't changed. 9 + 10 + ## SvelteKit Version Hash 11 + 12 + SvelteKit includes a unique "version hash" in its build output by default. This hash changes the hash of the main Svelte bundle and every chunk that depends on it. Since Wisp detects changes by blob hash, this forces a full re-upload of all JavaScript chunks on every deploy. 13 + 14 + For small sites this doesn't matter much, but for large apps with many chunks (e.g., code editors, pastebins) you can hit deployment rate limits because you're re-uploading hundreds of unchanged files on every deploy. 15 + 16 + ### Fix 17 + 18 + Set a fixed version name in `svelte.config.js`: 19 + 20 + ```js 21 + /** @satisfies {import('@sveltejs/kit').Config} */ 22 + const config = { 23 + kit: { 24 + version: { 25 + name: '1' 26 + } 27 + } 28 + }; 29 + 30 + export default config; 31 + ``` 32 + 33 + This keeps the version hash stable across builds. Only chunks whose actual content changed will be re-uploaded. 34 + 35 + > **Note:** If you rely on SvelteKit's version detection for cache busting (e.g., detecting when a new version of your app has been deployed), a fixed version name will disable that behavior. For most static sites on Wisp this is fine since cache invalidation is handled by the platform.

History

1 round 0 comments

niri.pet submitted #0 2d

1 commit

expand

fe0f29ed

docs: add blob reuse & framework caveats guide

merge conflicts detected

expand

docs/astro.config.mjs:31

expand 0 comments

Configure Feed

Configure Feed

History