Configuration

The Starlight Docsearch Typesense plugin is configured in your project’s astro.config.mjs file:

import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import starlightDocSearchTypesense from 'starlight-docsearch-typesense';
export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightDocSearchTypesense({
          // Configuration options go here.
        }),
      ],
      title: 'My Docs',
    }),
  ],
});

Configuration options

You can pass the following options to starlightDocSearchTypesense():

Property	Type	Description
typesenseCollectionName Required	string	The name of the Typesense collection to search. If using typesense-docsearch-scraper, it must match the index_name field in the scraper config file.
typesenseServerConfig Required	object	Configuration object for connecting to the Typesense server. See Typesense Server Config below.
typesenseSearchParameters	SearchOptions	Additional Typesense search parameters to fine-tune search behavior (e.g., filters, facets, ranking).
disableUserPersonalization default: false	boolean	Disables storing recent searches and favorites in local storage.
initialQuery	string	Initial query string to prefill the search box when the component first renders.

typesenseServerConfig

Property	Type	Description
apiKey Required	string	The API key used to authenticate with the Typesense server.
nodes Required	Array<Node>	List of Typesense nodes.
randomizeNodes	boolean	Randomizes the order of nodes for load balancing.
nearestNode	Node	The node prioritized for making requests, usually the load-balanced endpoint.
connectionTimeoutSeconds	number	Connection timeout for API calls, in seconds.
healthcheckIntervalSeconds	number	Frequency to perform health checks for failed nodes.
numRetries	number	Number of retry attempts for failed requests.
retryIntervalSeconds	number	Delay between retry attempts, in seconds.
sendApiKeyAsQueryParam	boolean	Sends the API key as a query parameter instead of a header.
useServerSideSearchCache	boolean	Enables the server-side search cache feature.
cacheSearchResultsForSeconds	number	Duration to cache search results.
additionalHeaders	Record<string, string>	Custom HTTP headers to send with every request.
logLevel	'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'	Sets the verbosity level for client logs.

Additional DocSearch options

You can extend the plugin with custom DocSearch client behavior in a separate configuration file, similar to the official @astrojs/starlight-docsearch plugin.

1. Create a TypeScript file exporting your DocSearch configuration.

   src/config/docsearch.ts

   import type { DocSearchClientOptions } from 'starlight-docsearch-typesense';
   
   export default {
     typesenseCollectionName: 'YOUR_COLLECTION_NAME',
     typesenseServerConfig: {
       nodes: [{ url: 'https://typesense-1.example.net:443' }],
       apiKey: 'YOUR_SEARCH_API_KEY',
     },
     getMissingResultsUrl({ query }) {
       return `https://github.com/typesense/typesense-docsearch.js/issues/new?title=${query}`;
     },
     // ...
   } satisfies DocSearchClientOptions;

2. Pass the path to your configuration file to the Starlight DocSearch plugin through clientOptionsModule.

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import starlightDocSearchTypesense from 'starlight-docsearch-typesense';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Site with DocSearch',
         plugins: [
           starlightDocSearchTypesense({
             clientOptionsModule: './src/config/docsearch.ts',
           }),
         ],
       }),
     ],
   });