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/client2. 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=...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.
---
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>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
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) }
}<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}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:
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.
Next.js SDK
Install @rootsmithio/next in a Next.js App Router site so RootSmith pages render on your domain and refresh the moment you publish.
Static sites
Publish to a Next.js static export, Astro, Hugo, Jekyll, Eleventy, or another static site with a deploy hook. RootSmith starts a new build of your site each time you publish.