Use the Search SDK and API

This guide is for developers. It shows how to add Uniform Search to a Next.js app. It also shows how to call the Search SDK and the Search API from your own code.

How the parts fit together#

Your front end uses 4 parts of Uniform Search:

Business users build search pages from the search components in Canvas. The search components call the Search API through the Search SDK. For custom interfaces, you can use the Search SDK or the Search API directly.

Add search to your Next.js app in 30 minutes or less#

You can add Uniform Search in 2 ways:

• Ask an AI coding assistant to do the work. This is the fastest path.
• Do the steps by hand.

In both ways, you first get the search URL and the search API key from the Uniform Search tool.

Get the search URL and the search API key#

The Connect drawer in the Uniform Search tool shows the search URL of your project. It also makes the search API key.

1. In your Uniform project, select Tools > Uniform Search in the project navigation.

2. In the status strip, click Connect.

   

   The Connect button in the status strip opens the Connect drawer.

   The Connect your frontend drawer opens.

3. Click Generate key.

   

   Generate a search API key in the Connect drawer.

   warning

   The drawer shows the full key 1 time only. You cannot get the key again later. If you lose the key, you must rotate it.

4. Click Copy as .env to copy the search URL and the search API key.

   

   Copy the new key before you close the drawer.

5. Paste the values into the .env.local file of your Next.js project.

6. Click I’ve stored the key.

The copied values look like this:

If your project has more than one locale, add the default locale of your project:

Next.js adds NEXT_PUBLIC_ values to the JavaScript bundle when it builds the app. After you change a value, build and deploy the app again.

Ask your coding assistant to add Uniform Search#

The Uniform agent skills include a skill for Uniform Search. The skill teaches your AI coding assistant the correct steps for your project.

1. Install the Uniform agent skills for your coding assistant. Refer to Uniform agent skills.
2. Add the search URL and the search API key to .env.local. Refer to Get the search URL and the search API key.
3. Open your Next.js project in your coding assistant.
4. Enter a prompt, for example: "Add Uniform Search to my app."

The assistant runs create-uniform-search, installs the Search SDK, and registers the search components. It also checks the environment variables and the theme. The assistant does not push the component definitions. It gives you the command. Do the steps in Push the component definitions and Publish a search page.

Scaffold the search components by hand#

The create-uniform-search tool copies the search components, the helpers, and the component definitions into your project.

1. Find the base folder of the @/* import alias in tsconfig.json. For ./*, the base is .. For ./src/*, the base is src.

2. Go to the folder that contains the package.json of your project.

3. Run the tool. Replace BASE with the base folder and LOCALE with the default locale of your project.

   npx -y create-uniform-search@latest --dir . --components --no-deploy --src-root BASE --locale LOCALE

   CopyCopied!

4. Install the Search SDK:

   npm install @uniformdev/search@latest

   CopyCopied!

5. Make sure that your project has the packages @uniformdev/next-app-router-client and @uniformdev/context. The search components import them.

6. Import the theme file from your global stylesheet. For Tailwind CSS 4, add this line after @import "tailwindcss";:

   app/globals.css

   @import "../styles/search-theme.css";

   CopyCopied!

   tip

   For Tailwind CSS 3, copy the mono colors from styles/search-theme.css into theme.extend.colors.mono in tailwind.config.js.

7. Download the Uniform Context manifest. The behavior relevancy helpers read the enrichment categories from this file.

   npx uniform context manifest download --output ./lib/uniform/manifest.json

   CopyCopied!

8. If your project does not use cacheComponents: true in next.config, change components/search/Recommendations.tsx to fetch the project map paths directly. Refer to Recommendations without cache components.

9. Do a type check and correct the errors that it shows:

   npx tsc --noEmit

   CopyCopied!

Command options#

The tool reads UNIFORM_API_KEY and UNIFORM_PROJECT_ID from .env, then from .env.local, then from the environment. If your project is not on https://uniform.app, set UNIFORM_CLI_BASE_URL to the host of your Uniform project.

Files that the tool adds#

The tool does not install the Search SDK, add environment variables, import the theme, or change your component resolver. When the tool stops, it shows the next steps.

lib/search/searchClient.ts makes the search client from the 2 environment variables:

Recommendations without cache components#

The Recommendations component uses lib/search/cachedProjectMapPaths.ts. This helper uses the 'use cache' directive, and Next.js builds it only when cacheComponents is true. When you turn on cacheComponents, the change applies to all routes of your app.

If you do not want to turn on cacheComponents, do these steps:

1. In components/search/Recommendations.tsx, replace the import of getCachedPathsByNodeId with this code:

   components/search/Recommendations.tsx

   import { fetchPathsByNodeId } from '@/lib/search/projectMapClient'; const SEARCH_API_URL = process.env.NEXT_PUBLIC_UNIFORM_SEARCH_API_URL ?? '';

   CopyCopied!

2. In the same file, replace the line that calls getCachedPathsByNodeId with this line:

   components/search/Recommendations.tsx

   const pathsByNodeId = locale && SEARCH_API_URL ? await fetchPathsByNodeId(SEARCH_API_URL, locale) : {};

   CopyCopied!

3. Delete lib/search/cachedProjectMapPaths.ts.

fetchPathsByNodeId keeps the paths in memory for each locale. Each server process sends 1 request for each locale.

Register the components in the resolver#

The search components use the compat component shape. Register them with createAdapterResolveComponentFunction in adapted mode. Keep the type IDs exactly as shown. They must match the component definitions.

If your project already uses createAdapterResolveComponentFunction, add searchMappings to its mappings.

If your project uses a plain resolveComponent function, send the search types to the adapter first. Do not call the adapter as a fallback. The adapter returns a "Not implemented" component for types that it does not know.

The search components are client components. Do not remove the 'use client' directive. The Recommendations component is a server component.

Push the component definitions#

The push adds the search component definitions, the block types, the category, and the patterns to your Uniform project.

1. Add UNIFORM_API_KEY and UNIFORM_PROJECT_ID to the .env file of your project. The API key must have permission to create components, content types, and patterns.

2. Go to the folder that contains uniformsearch.config.js.

3. Optional: show the changes before you push them:

   npx @uniformdev/cli sync push --config ./uniformsearch.config.js --what-if

   CopyCopied!

4. Push the definitions:

   npx @uniformdev/cli sync push --config ./uniformsearch.config.js

   CopyCopied!

5. In Uniform, open the component definition of your page. Add Search Engine to the allowed components of the content slot.

6. If you want a search box in your site header, add Search Autocomplete to the allowed components of the header slot.

7. Open the Search Engine pattern. Make sure that the titles of the Order By items in Search Sort are in the language of your site. Change them if necessary.

Publish a search page#

1. In Uniform, create a composition for your search page, for example at the path /search.

2. Add the Search Engine pattern to the content slot. You can also add a Search Engine component and fill its slots.

3. On the Search Engine component, set Query By and Entry Url Mapping.

4. Add a Search Facet to the Facet Container for each field that visitors can filter by.

5. Look at the preview and make sure that results show.

6. Publish the composition.

7. Build and deploy your app.

For all component parameters, refer to Build search experiences.

Rotate the search API key#

Rotate the key when you think that someone else has it, or when your security policy tells you to. The old key continues to work for 24 hours. In this time, update all front ends that use it.

1. In the Uniform Search tool, click Connect.

2. Click Rotate API key.

3. In the Rotate the search key? dialog, click Rotate key.

   

   The old key continues to work for 24 hours after you rotate it.

4. Copy the new key.

5. Update NEXT_PUBLIC_UNIFORM_SEARCH_API_KEY in all front ends. Then build and deploy them.

6. Optional: to stop the old key before the 24 hours end, click Revoke now. Then confirm.

   

   Revoke the previous key when all front ends use the new key.

Search SDK reference#

The Search SDK is the npm package @uniformdev/search. It needs React 18 or later only for the React entry point.

Entry points#

createSearchClient#

createSearchClient(config) returns a search client with 2 functions: performSearch and trackClick.

performSearch(params) sends a POST request to /api/search and returns the response. The function does not throw. If the request fails, it writes the status to the console, for example Search API error: 401. It then returns an empty result.

trackClick(params) reports a click on a result. Refer to Report clicks on results.

Search parameters#

performSearch accepts these parameters. The Search API accepts the same fields in the request body.

If you do not set a typo parameter, the search index uses its default value.

Helpers and constants#

SearchProvider#

SearchProvider keeps the search state for a search page. It sends the search requests and gives the results to the components inside it. The Search Engine component adds a SearchProvider for you. Do not add one to layout.tsx.

SearchProvider also accepts orderBy and pageSizes. These props are for older compositions only. For new code, register the options from the child components.

The provider keeps the state in the URL query string. Visitors can share and bookmark a search:

When a visitor selects a value in a facet, the provider also calculates the facet counts without the filter of that facet. Thus the facet continues to show all of its options.

The provider reads the URL in the browser. It gets the results after the page loads in the browser.

useSearch#

useSearch() returns the search state and the functions that change it. Use it in a component inside SearchProvider. Outside a provider, it throws an error.

The provider requests facet counts only for the facets that you register. This example shows a search box, a facet, and a list of results:

useAutocomplete#

useAutocomplete(options) gives the state and the ARIA attributes for a search box with suggestions. It does not need SearchProvider. Use it in a site header or a dialog.

The hook returns query, setQuery, suggestions, isLoading, isOpen, activeIndex, activeItem, open, close, clear, and selectItem. It also returns the prop getters getLabelProps, getInputProps, getListboxProps, and getItemProps. The prop getters add the WAI-ARIA combobox attributes and the keyboard support: Arrow Up, Arrow Down, Home, End, Enter, and Escape.

The search page reads the search URL key. Thus /search?search=QUERY opens the search page with the query.

useSimilarItems#

useSimilarItems(docId, options) returns the documents that are most similar in meaning to one document. Use it for "related articles" or "similar products". It does not need SearchProvider.

The hook returns { items, loading, error, degraded, refetch }. The source document is not in items.

This hook needs semantic search. If semantic search is off, the results are keyword results and degraded is true. To turn on semantic search, contact your Uniform representative.

Pagination hooks#

useSearchPagination(siblingCount?) reads the state of SearchProvider. It returns { pages, currentPage, hasPrev, hasNext, goToPage, goToPrev, goToNext, isLoading }.

pages contains page numbers that start at 1. It also contains the DOTS value, '...', for gaps. currentPage and goToPage use page numbers that start at 0.

usePagination({ currentPage, totalCount, perPage, siblingCount }) calculates the same page list from your own values. It does not need SearchProvider.

Result URLs#

A result does not always have a URL. The URL resolver makes the URL of each result from the Entry Url Mapping parameter.

createDefaultUrlResolver(configs, { pathsByNodeId, locale }) returns a function (hit) => string | undefined. Each config is a SearchItemConfig:

The resolver replaces each :token with the mapped field of the result. For a composition, the resolver uses the path field of the result.

To change the URLs of all results in a part of the page, wrap it in SearchItemUrlResolverProvider. useUrlResolver() returns your resolver, or the default resolver of the Search Engine component.

The scaffolded components get the project map paths from the Search API with the search API key. You do not need to call this endpoint yourself.

Behavior relevancy#

Behavior relevancy puts the results that match the interests of the visitor first. It uses the enrichment scores from Uniform Context. For information about enrichments, refer to Enrichments.

To use behavior relevancy in code:

1. Get the visitor scores with useScores() from @uniformdev/next-app-router-client.
2. Reduce the scores with resolveEnrichmentBoost. It keeps the highest value in each category and the 3 highest categories.
3. Give the result to the enrichmentBoost prop of SearchProvider.
4. Set the sort order to behavior.

resolveEnrichmentBoost accepts these options:

The Search Engine component does these steps for you. Authors turn on behavior relevancy in Canvas. They add an Order By item with the field Behavior relevancy (Uniform Context) to Search Sort, or they select it in Predefined Sort.

If a visitor has no scores, the results have the default relevance order. The facet counts and the total do not change.

Recommendations#

The Recommendations component shows the content that matches the interests of the visitor. It is a server component in components/search/Recommendations.tsx.

The component reads the visitor scores from the ufvd cookie on the server. It sends 1 search request with an empty query and the behavior sort order. It renders inside <Suspense>, so the rest of the page can render first.

This example shows the same request in your own server component:

Put the component inside <Suspense>. It reads a cookie, so Next.js renders it for each request.

Report clicks on results#

trackClick(params) reports a click on a result to search analytics. The data shows in the Analytics tab of the Uniform Search tool. The function does not throw and does not stop the navigation.

The scaffolded Search Results component does not report clicks. To report clicks, add trackClick to your result list:

If analytics or click reports are off for the project, the Search API accepts the click and does not record it. For the analytics settings, refer to Operate search.

Search API reference#

Use the Search API when you cannot use the Search SDK, for example from another language.

All requests go to the search URL from the Connect drawer, for example https://YOUR_SEARCH_API_HOST. Send the search API key in the x-api-key header.

POST /api/search#

Send a JSON body with the Content-Type: application/json header. All fields are optional. For the full list, refer to Search parameters.

Filters#

filters is an object. Each key is a field name with an operator. If there is more than 1 key, a document must match all keys.

For a range, send [gte] and [lte] for the same field. The Search API escapes all filter values.

baseFilterBy and filters apply together. A document must match both.

Sort order#

You can sort only by fields that are sortable in the schema. For more information, refer to Configure search.

predefinedSort is a sort that an editor sets on the Search Sort component. It applies before orderBy. orderBy then sorts the documents that have the same position. It has 3 forms:

In the conditional form, documents that match a rule with a higher score come first. With "direction": "asc", the matched documents come last. A document gets the highest score of the rules that it matches. The Search API ignores a predefined sort that is not valid.

A request can have a maximum of 3 sort clauses. A request can have only 1 conditional sort. If a conditional predefined sort and a behavior sort order are both in a request, the predefined sort wins. The response then contains a warning.

Behavior relevancy#

• cat is the enrichment category ID. key is the value ID in the category.
• The Search API uses a maximum of 3 signals. maxSignals cannot increase this limit.
• Scores must be more than 0. The Search API changes scores more than 100 to 100.
• The Search API ignores signals that are not valid. It does not return an error.
• If there are no signals, the results have the default relevance order.

Send the reduced signals only. Use resolveEnrichmentBoost from the Search SDK, or send the highest value of each category.

Retrieval modes#

If you do not set mode, the Search API uses hybrid when semantic search is on for the project. Otherwise it uses keyword. In most cases, do not set mode. Use keyword when meaning-based matches are wrong, for example for a lookup of part numbers.

Semantic search is not available in some conditions. Then the Search API returns keyword results with HTTP status 200, and degraded is true.

• In hybrid mode, the Search API ignores a field orderBy and adds a warning.
• A behavior sort order with signals, or a valid predefined sort, turns off semantic retrieval for the request.
• similarTo returns the documents that are most similar to one document. The source document is not in the results. The ID can contain only letters, digits, ., _, :, and -.

To turn on semantic search, contact your Uniform representative.

Response#

Each result has the stored fields of the document from your schema, and these fields:

Localized fields have their plain names in the result. The response does not contain the vector data.

Examples#

POST /api/track#

Reports a click on a result. Use the same header and key as for search.

The response is { "success": true, "recorded": true }. When analytics or click reports are off, recorded is false.

Status codes#

Security#

• The search API key is read-only. It can search the index, report clicks, and read the page paths of the project map. It cannot change content or settings.
• The search API key works for 1 project only. A request with a projectId of a different project gets 401.
• The search API key can be in browser code. It is safe in NEXT_PUBLIC_ variables.
• Keep push API keys on the server. A push API key can write documents to the search index. Never put a push API key in browser code or in a NEXT_PUBLIC_ variable. For push sources, refer to Configure search.
• Uniform Search accepts browser requests only from the allowed origins of your deployment. To add the domain of your site, contact your Uniform representative.
• Only team admins can open the Uniform Search tool and make or rotate keys.

Cache and performance#

• Search requests use POST. Thus a shared cache does not keep a copy of the results. This is important for behavior relevancy: the results of one visitor never go to a different visitor. Do not add a public cache in front of search requests.
• The first results page can render on the server. Call performSearch in a server component, as in the Recommendations example.
• SearchProvider runs in the browser. It gets the results after the page loads.
• SearchProvider waits 300 milliseconds after the last keystroke before it sends a request. useAutocomplete waits 150 milliseconds. You can change these values.
• SearchProvider and the hooks ignore responses that come back after a newer request.
• The project map paths stay in memory for each locale. The Recommendations component can also keep them in the Next.js cache for some minutes.
• When authors publish content, Uniform Search updates the search index. Your app does not need to do anything.

Troubleshooting#

Test a query in the Search tab to compare it with the results in your app.

Next steps#

• Configure search: select search sources, set up the schema, and tune relevance.
• Build search experiences: build search pages in Canvas.
• Operate search: re-index content, manage keys, and read analytics.
• Uniform agent skills: let your coding assistant add search for you.