Skip to Content
AeroSearch Docs
Quickstarts

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

  1. A Project search-scoped API key.
  2. A Collection id with Documents.
  3. 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.mjs

The 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.

On this page