RootSmith Docs

Other JavaScript frameworks

Use @rootsmithio/client to show RootSmith pages in Astro, SvelteKit, Nuxt, or any JavaScript server, and refresh them the moment you publish.

@rootsmithio/client reads published pages from RootSmith, renders their Markdown to safe HTML, and answers the signed refresh that RootSmith sends when you publish. It works in any JavaScript server that uses the standard Request and Response objects. For Next.js, use the Next.js SDK, which adds caching and metadata.

1. Install the package

npm install @rootsmithio/client

2. Add your environment variables

In Publishing, choose Astro, SvelteKit, Nuxt, or another JavaScript server, then select Set up SDK and choose Do it yourself. The dialog shows these values for your site. Use your agent has a prompt for your coding agent instead. Keep them on your server.

ROOTSMITH_SITE_ID=00000000-0000-0000-0000-000000000000
ROOTSMITH_CONNECTION_SECRET=...
lib/rootsmith.ts
import { createRootSmith } from "@rootsmithio/client"

export const rootSmith = createRootSmith({
  siteId: process.env.ROOTSMITH_SITE_ID!,
})

The client reads https://api.rootsmith.io. Pass apiUrl to read another address.

getPage(path) returns the page, null for a missing page, or { redirect } when the page was merged into another page. Send a 308 redirect for that case. listAllPages() returns every published page, for a sitemap or a static build.

For an index page, such as /blog, pass the page type's URL prefix and sort the posts with the newest first. Published pages never sit at the prefix itself, so your own route owns it:

const posts = await rootSmith.listAllPages({ prefix: "/blog", sort: "newest" })

To split a long index into numbered pages, use listPages. See Pagination.

renderHtml(page) returns the page body as HTML. Raw HTML in the Markdown is removed, unsafe links are dropped, and images load only from the page's own domain. Pass { imageOrigins: ["https://cdn.example.com"] } to allow other image hosts. The HTML includes the version marker that RootSmith uses to confirm the page is live, so keep it in the page.

3. Add the page and refresh routes

Astro

Use server output (output: "server") with an adapter.

src/pages/[...path].astro
---
import { renderHtml } from "@rootsmithio/client"
import { rootSmith } from "../lib/rootsmith"

const found = await rootSmith.getPage(`/${Astro.params.path ?? ""}`)
if (!found) return new Response(null, { status: 404 })
if ("redirect" in found) return Astro.redirect(found.redirect, 308)
---

<html lang="en">
  <head>
    <title>{found.title}</title>
    <meta name="description" content={found.description} />
    <link rel="canonical" href={found.url} />
  </head>
  <body>
    <h1>{found.title}</h1>
    <Fragment set:html={renderHtml(found)} />
  </body>
</html>
src/pages/api/rootsmith.ts
import type { APIRoute } from "astro"
import { createRootSmithHandler } from "@rootsmithio/client"

const handler = createRootSmithHandler()
export const prerender = false
export const POST: APIRoute = ({ request }) => handler(request)

SvelteKit

src/routes/[...path]/+page.server.ts
import { error, redirect } from "@sveltejs/kit"
import { renderHtml } from "@rootsmithio/client"
import { rootSmith } from "$lib/rootsmith"
import type { PageServerLoad } from "./$types"

export const load: PageServerLoad = async ({ params }) => {
  const found = await rootSmith.getPage(`/${params.path}`)
  if (!found) error(404)
  if ("redirect" in found) redirect(308, found.redirect)
  return { page: found, html: renderHtml(found) }
}
src/routes/[...path]/+page.svelte
<script lang="ts">
  let { data } = $props()
</script>

<svelte:head>
  <title>{data.page.title}</title>
  <meta name="description" content={data.page.description} />
  <link rel="canonical" href={data.page.url} />
</svelte:head>

<h1>{data.page.title}</h1>
{@html data.html}
src/routes/api/rootsmith/+server.ts
import { createRootSmithHandler } from "@rootsmithio/client"
import type { RequestHandler } from "./$types"

const handler = createRootSmithHandler()
export const POST: RequestHandler = ({ request }) => handler(request)

Nuxt and other servers

Use the same two parts. Read the page with getPage in a server route and render renderHtml(page). For the refresh route, pass a standard Request to the handler. In Nuxt, use toWebRequest(event) from h3:

server/api/rootsmith.post.ts
import { createRootSmithHandler } from "@rootsmithio/client"

const handler = createRootSmithHandler()
export default defineEventHandler((event) => handler(toWebRequest(event)))

The handler reads ROOTSMITH_SITE_ID and ROOTSMITH_CONNECTION_SECRET from process.env when a request arrives. On a runtime without process.env, pass siteId and secret to createRootSmithHandler.

4. Deploy and connect

Deploy your site. In the setup dialog, save /api/rootsmith as the endpoint and select Save and verify.

Caching

These examples read RootSmith on each request, so a refresh has nothing to clear. If you cache pages, pass a refresh callback that clears your cache for the path:

createRootSmithHandler({ refresh: (path) => cache.delete(path) })

The callback gets the path of the page that changed. If you cache index pages, such as /blog, clear them too.

It must finish before the handler returns. To read through your framework's cache, pass init, such as init: () => ({ cache: "force-cache" }). Its fields are added to each read request.

On this page