Web Framework
Moss + Next.js: Semantic Search with Server Actions
Moss integrates with Next.js using Server Actions for a clean client-server search pattern. Load the index on the server at module initialization, expose a search function with "use server", and call it from client components with useTransition for non-blocking search. Works with both App Router and Pages Router.
Benefits
Why Use Moss with Next.js
Server Actions pattern: "use server" keeps credentials server-side, client components call searchMoss() directly
Module-level index loading: loadIndex() runs once, all subsequent queries return in under 10ms
useTransition for non-blocking search: UI stays responsive while results load
Works with Next.js App Router (Server Actions) and Pages Router (API routes)
TypeScript-native: full type safety with MossClient, QueryResult, and QueryOptions
Integration
Quick Start
// app/actions/search.ts
"use server"
import { MossClient, type QueryResult } from "@moss-dev/moss"
const client = new MossClient(
process.env.MOSS_PROJECT_ID!,
process.env.MOSS_PROJECT_KEY!,
)
// Load index once at module init
let loaded = false
async function ensureLoaded() {
if (!loaded) {
await client.loadIndex("knowledge-base")
loaded = true
}
}
export async function searchMoss(query: string): Promise<QueryResult> {
await ensureLoaded()
return client.query("knowledge-base", query, { topK: 5 })
}
// app/components/search.tsx (client component)
// "use client"
// const [results, setResults] = useState<QueryResult | null>(null)
// const [pending, startTransition] = useTransition()
// startTransition(async () => {
// const res = await searchMoss(query)
// setResults(res)
// })Setup
Get Started in 3 Steps
Install the SDK
Run npm install @moss-dev/moss to add the Moss TypeScript SDK to your Next.js project.
Create a Server Action
Create a "use server" file that initializes MossClient, loads the index at module level, and exports a searchMoss() function.
Call from client components
Import searchMoss in a client component. Use useTransition to call it non-blockingly and render results.
FAQ
Frequently asked questions
Explore