Add clientOptionsModule option to DocSearch plugin

[KianNH]

Description

• Closes DocSearch component supports custom link for results footer component #2806
• Adds a clientOptionsModule option to the starlightDocSearch plugin.
  • This takes the shape of a path to a JavaScript or TypeScript file which will be imported (if present) and merged with existing options in the starlight/docsearch-config virtual module.
  • If an option exists in both, i.e appId, the option in the clientOptionsModule file will be used.

Considerations

• Updating documentation

starlight/docs/src/content/docs/guides/site-search.mdx

Lines 111 to 118 in 66a4131

	#### DocSearch configuration
	The Starlight DocSearch plugin also supports customizing the DocSearch component with the following additional options:
	- `maxResultsPerGroup`: Limit the number of results displayed for each search group. Default is `5`.
	- `disableUserPersonalization`: Prevent DocSearch from saving a user’s recent searches and favorites to local storage. Default is `false`.
	- `insights`: Enable the Algolia Insights plugin and send search events to your DocSearch index. Default is `false`.
	- `searchParameters`: An object customizing the [Algolia Search Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).

• Tests

Whilst this is probably not a large enough package to warrant it, I did setup try out setting up Vitest for this package where vitePluginDocSearch is passed in vitest.config.ts but since it would need a lot of work to setup a harness to test starlightDocSearch I opted against including it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 090f60f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight-docsearch	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	090f60f
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67925330c614f000082a3161
😎 Deploy Preview	https://deploy-preview-2822--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 99 (🟢 up 16 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[HiDeoo]

Not a complete review or request for some changes, but I left a few comments mostly regarding the JSDoc to start some discussion around the approach.

One other question coming to mind is if we should expose a defineDocSearchConfig helper just for the typings or something similar?

[HiDeoo]

I think this should specify what the default export should be.

[delucis]

Looking good @KianNH! Seconding @HiDeoo’s idea to make the option module all-or-nothing, so if you use that, you move all config there, unless there’s a reason not to do that anyone can see.

I also agree we should export something to help with typing the options module. Given this module will end up in client-side code, I might suggest just a type rather than a defineClientOptions() utility just to avoid the extra no-op function in the bundle. (Would also allow us to export it directly from @astrojs/starlight-docsearch rather than needing a dedicated file just for that.) That would help us assert that e.g. you shouldn’t set the container property which Starlight takes care of.

So something like:

import type docsearch from '@docsearch/js';

export type DocSearchClientOptions = Omit<Parameters<typeof docsearch>[0], 'container'>;

And then users can write config as:

import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch';

export default { 
  // ...
} satisfies DocSearchClientOptions;