forked from
nekomimi.pet/wisp.place-monorepo
Monorepo for wisp.place. A static site hosting service built on top of the AT Protocol.
docs: add blob reuse & framework caveats guide
Documents SvelteKit version hash breaking Wisp blob reuse,
with workaround and tradeoffs. References #37.
+36
+1
docs/astro.config.mjs
+1
docs/astro.config.mjs
+35
docs/src/content/docs/guides/blob-reuse.md
+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.