React quickstart
Embed permission-aware search in React with the TypeScript SDK and UI components.
Goal: render an ACL-scoped search box and hits with @aerosearch/sdk-typescript
and @aerosearch/ui-components, receiving HTTP 200 in under five minutes.
Prerequisites
- A Project search-scoped API key.
- A Collection id with Documents.
- A React 18+ app (Vite or Next.js client components).
Install both packages (available after the first registry release):
The generated sample below includes the exact install command.
Pass your Cell host, search key and Collection id as SearchPage props.
The sample is a Next.js client component. In Vite, mount it with createRoot
from react-dom/client; use the standard React TypeScript template and its
react-jsx setting. The sample uses props in both frameworks, so it needs no
Node globals or framework-specific environment substitution. Supply a real
server-minted endUserToken prop only when your application has one.
Sample
# generated-from-contract: contracts/openapi/v1.yaml
npm install @aerosearch/sdk-typescript @aerosearch/ui-components
// generated-from-contract: contracts/openapi/v1.yaml
"use client";
import { useEffect, useMemo, useRef, useState } from "react";
import { AeroSearch, type CollectionClient, type SearchResponse } from "@aerosearch/sdk-typescript";
import { Hits, SearchBox } from "@aerosearch/ui-components";
export function SearchPage({
baseUrl = "https://api.aerosearch.team",
apiKey = "ask_YOUR_PROJECT_SEARCH_KEY",
collectionId = "col_help",
endUserToken,
}: { baseUrl?: string; apiKey?: string; collectionId?: string; endUserToken?: string }) {
const collection = useMemo(
() => new AeroSearch({ baseUrl, apiKey, endUserToken }).collection(collectionId),
[baseUrl, apiKey, collectionId, endUserToken],
);
const [scope, setScope] = useState({ collection, version: 0 });
if (scope.collection !== collection) {
setScope({ collection, version: scope.version + 1 });
return null;
}
// Remount before rendering results under a different Principal or Collection.
return <ScopedSearch key={scope.version} collection={collection} />;
}
function ScopedSearch({ collection }: { collection: CollectionClient }) {
const [response, setResponse] = useState<SearchResponse>();
const latestRequest = useRef(0);
useEffect(() => () => { latestRequest.current += 1; }, []);
async function onSearch(query: string) {
const request = ++latestRequest.current;
const next = await collection.search({ query, limit: 10 });
if (request === latestRequest.current) setResponse(next);
}
return (
<>
<SearchBox collection={collection} onSearch={onSearch} />
{response ? <Hits response={response} /> : null}
</>
);
}
// Equivalent wire shape (SearchRequest):
// POST /v1/collections/col_help/search
// { "query": "reset password", "limit": 10 }
The end-user identity travels only in X-AeroSearch-End-User-Token (or the SDK
endUserToken option). Never put an end-user token in the request body.
Verify
The install smoke packs both packages, installs them in an empty app, strictly type-checks the sample and renders a hit from the local double:
node --test tests/install/npm-install-smoke.test.mjsThe production workflow renders the same installed sample in Chromium against a seeded real Cell. Configure the expected Document id, title and query and deploy a Cell containing WP-04 before running it. WP-04 answers browser preflights and returns wildcard CORS; per-key Origin restrictions await WP-13.