About Next.js
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.
Why Use Moss with Next.js
01
Server Actions pattern
"use server" keeps credentials server-side, client components call searchMoss() directly
02
Module-level index loading
loadIndex() runs once, all subsequent queries return in under 10ms
03
useTransition for non-blocking search
UI stays responsive while results load
04
Works with Next.js App Router and Pages Router
Server Actions for App Router, API routes for Pages Router
05
TypeScript-native
Full type safety with MossClient, QueryResult, and QueryOptions
Quick Start
"use server";
import { MossClient } from "@moss-js/moss";
const client = new MossClient(
process.env.MOSS_PROJECT_ID!,
process.env.MOSS_PROJECT_KEY!,
);
const indexName = process.env.MOSS_INDEX_NAME!;
const indexReady = client.loadIndex(indexName);
export async function searchMoss(query: string) {
await indexReady;
const results = await client.query(indexName, query, { topK: 5 });
return results.docs.map((doc) => ({
id: doc.id,
text: doc.text,
score: doc.score,
metadata: doc.metadata,
}));
}Get Started in 3 Steps
01
Install the SDK
Run npm install @moss-js/moss to add the Moss TypeScript SDK to your Next.js project.
02
Create a Server Action
Add a "use server" search action that initializes MossClient, loads the index once, and exposes searchMoss(query).
03
Call from a client component
Use useTransition to call searchMoss from the client so search stays non-blocking while results update.
Frequently asked questions
Ready to ship faster AI products?
Moss gives you production-ready semantic retrieval without infrastructure complexity.