diff --git a/docs/develop/dynamic-content.md b/docs/develop/dynamic-content.md new file mode 100644 index 00000000..c9a1770d --- /dev/null +++ b/docs/develop/dynamic-content.md @@ -0,0 +1,153 @@ +--- +title: Dynamic Content +id: dynamic-content +sidebar_label: Dynamic Content +--- + +:::warning +Under construction, set for major revisions to incorporate content from manifests, rout, and host your website pages +::: + + +## Feeds for Dynamic Content + +:::info +Although all data on Swarm is immutable, feeds provide an updatable reference that lets you simulate dynamic content. A feed is an append‑only sequence of updates that always resolves to its latest entry through a stable feed manifest. +::: + +:::tip +If you are not familiar with feeds, read: +- Bee docs: /docs/develop/tools-and-features/feeds/ +- Bee-JS docs: https://bee-js.ethswarm.org/docs/soc-and-feeds/ +::: + +Single‑page applications (SPAs) deployed on Swarm work best when their static assets can be updated independently. Instead of reuploading the entire site when one file changes, you can create a separate feed manifest for each asset. Each asset feed provides a stable URL that always resolves to the latest version of that file. + +## Why Use Per‑Asset Feeds + +- Each React/Vite build artifact (HTML, JS, CSS, images) becomes individually updatable. +- Every asset has a dedicated feed manifest with its own stable Swarm URL. +- Updating a single file only updates its feed; the rest of the site stays untouched. +- This keeps deployments small, fast, and cost‑efficient. + +## Architecture Overview + +| Asset | Feed Topic | Purpose | +|----------------------|-----------------|-----------------------------| +| Main site bundle | `website` | HTML/JS/CSS entry point | +| CSS theme | `main-css` | Global styling | +| JS bundle | `main-js` | Application logic | +| Images | `img-*` | Media resources | + +Each asset has: +- a private key +- a feed topic +- a feed manifest +- a stable Swarm URL (`bzz:///`) + +## Generate a Publisher Key + +```js +import crypto from "crypto"; +import { PrivateKey } from "@ethersphere/bee-js"; + +const hex = "0x" + crypto.randomBytes(32).toString("hex"); +const pk = new PrivateKey(hex); + +console.log("Private key:", pk.toHex()); +console.log("Address:", pk.publicKey().address().toHex()); +``` + +## Create a Feed for an Asset + +```js +import { Bee, PrivateKey, Topic } from "@ethersphere/bee-js"; + +const bee = new Bee("http://localhost:1633"); +const batchId = ""; + +const pk = new PrivateKey(""); +const topic = Topic.fromString("main-js"); +const owner = pk.publicKey().address(); + +const writer = bee.makeFeedWriter(topic, pk); +``` + +## Upload an Asset and Publish a Feed Update + +```js +const upload = await bee.uploadFile(batchId, "./dist/assets/index-398a.js"); +await writer.upload(batchId, upload.reference); + +const manifest = await bee.createFeedManifest(batchId, topic, owner); +console.log("JS Manifest:", manifest.toHex()); +``` + +Stable URL: + +``` +bzz:/// +``` + +This URL never changes, even when you replace the underlying file. + +## Updating an Existing Asset + +```js +const nextUpload = await bee.uploadFile(batchId, "./dist/assets/index-new.js"); +await writer.upload(batchId, nextUpload.reference); +``` + +No new manifest is created. The old URL now resolves to the updated file. + +## Referencing Asset Feeds in Your SPA + +Rather than referencing a static build hash, point your SPA to feed manifests. + +Example `index.html`: + +```html + + +``` + +Example React image reference: + +```jsx +Hero +``` + +This makes your deployment resilient to Vite’s changing file names, because Swarm fetches the latest version through the feed instead of the literal file path. + +## Example Deployment Workflow + +1. Build Vite: + ``` + npm run build + ``` + +2. For each file in `dist/`: + - assign (or reuse) a feed topic + - upload the file + - update its feed + - store the feed manifest hash in a hard‑coded list inside your SPA + +3. Rebuild your SPA to reference: + - `bzz:///` + - `bzz:///` + - `bzz:///` + +4. Upload only the *main* SPA entrypoint (often a small static HTML + JS shell) using `swarm-cli feed upload`. + +This gives you a fully working dynamic SPA with lightweight incremental updates. + +## Summary + +- Each build artifact gets its own updatable feed. +- Your SPA uses stable feed manifest URLs instead of build‑hashed filenames. +- Only changed files need to be uploaded. +- This keeps deployments fast while ensuring long‑lived URLs remain valid. + +The next section (not included here) expands this into a registry‑based system for large dynamic sites. + + diff --git a/docs/develop/host-your-website.md b/docs/develop/host-your-website.md index a530b4b8..880d5c05 100644 --- a/docs/develop/host-your-website.md +++ b/docs/develop/host-your-website.md @@ -478,4 +478,5 @@ This works across: * localhost (with a compatible RPC) * any ENS-compatible Swarm resolver -You do not need to encode the hash or use any additional tools. `bzz://` is sufficient. \ No newline at end of file +You do not need to encode the hash or use any additional tools. `bzz://` is sufficient. + diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md index ad9dce1f..e4f6778b 100644 --- a/docs/develop/introduction.md +++ b/docs/develop/introduction.md @@ -61,16 +61,17 @@ pagination_next: null Open guide -