# docusaurus-theme-search-typesense: DocSearch-style search for Docusaurus on your own Typesense backend

> A fork of @docusaurus/theme-search-algolia that points the DocSearch UI at Typesense instead of Algolia. This article covers what it does, how the theme wires into Docusaurus, and where it stops being the right choice.

**typesense/docusaurus-theme-search-typesense** — A fork of the awesome @docusaurus/theme-search-algolia library customized to work with Typesense

- Repository: https://github.com/typesense/docusaurus-theme-search-typesense
- Website: https://typesense.org/docs/guide/docsearch.html
- Stars: 84 · Forks: 24
- Language: TypeScript
- License: MIT
- Published: 2026-08-26 · Updated: 2026-08-26 · Language: en
- Canonical page: https://hysenlabs.com/projects/typesense-docusaurus-theme-search-typesense

## What docusaurus-theme-search-typesense replaces

Docusaurus ships a search theme built on Algolia DocSearch. The theme owns the UI: the search bar in the navbar, the modal, the keyboard shortcut, the result list. The index behind it lives on Algolia's servers, populated by a crawler you do not run. docusaurus-theme-search-typesense keeps the interface and swaps the backend. It is, in the README's words, "a fork of the awesome @docusaurus/theme-search-algolia library customized to work with Typesense." The audience is documentation teams who already run Typesense, or who want search on infrastructure they control rather than a hosted third party. The homepage points at typesense.org/docs/guide/docsearch.html for the full setup path, and that page is where the scraper half of the story lives. This package is only the front end.

## How the theme connects Docusaurus to a Typesense cluster

The package is a Docusaurus theme plugin, not a standalone search service. Its package.json exports two entry points: the theme itself via lib/index.js, and a client bundle via ./client. The client bundle is what the browser loads. Under the hood the dependencies include typesense-docsearch-react and typesense-instantsearch-adapter, so the search UI is the DocSearch React component wired to Typesense through an adapter rather than to Algolia. The Algolia helper library, algoliasearch-helper, is still a dependency, which is expected in a fork of the Algolia theme: the fork reuses the query-state plumbing and changes the transport. The practical consequence is that the theme issues live queries against a Typesense host at search time. There is no prebuilt index shipped with your site, and no build-time crawl. If the cluster is unreachable, the search box has nothing local to fall back on. That is a different failure profile from a static local-search plugin, and it is the single most important architectural fact about this package.

## Installing it and wiring search into a Docusaurus site

The README defers detailed setup to the Typesense DocSearch guide, so treat that page as the source of truth for the full sequence. What the repository does state is the version matrix. For the current line, 0.27.x supports Docusaurus >= 3.9.0 < 4.0.0 and Node.js >=20. The 0.26.x line supports Docusaurus 3.9.x, 0.25.x supports 3.8.x, and 0.24.x supports 3.7.x. Node 20 is the floor for 0.26.x and 0.27.x; 0.24.x and 0.25.x still allow Node 18. Check that table before you install anything, because a mismatch here is the most common way this setup fails.

Install the package with your package manager. The repository is a Yarn project, but the package is published to npm under the name docusaurus-theme-search-typesense, so either works.

```bash
yarn add docusaurus-theme-search-typesense
```

After that, start the dev server and open the site. You should see the familiar DocSearch-style search box in the navbar. What you will not see, if the index has not been created yet, is any result: the theme queries a cluster that must already contain the scraped records. The Typesense guide covers running the DocSearch scraper first, then installing this plugin. Doing it in the other order leaves you with a working search box and an empty result list, which is confusing the first time.

## The scraper dependency and other real limits

This package does not index your documentation. The crawl is handled by the DocSearch scraper, which the Typesense guide documents separately. That means adopting this theme means operating two things: a Typesense server and a scraper pipeline that keeps the index current. If you change a page and do not re-crawl, search returns stale content. There is no build-time hook in this repository that triggers a re-index when Docusaurus builds.

The compatibility table is narrow by design. 0.27.x targets Docusaurus 3.9.x and above but below 4.0.0. If you are pinned to an older Docusaurus major, you are stuck on an older theme release or you are not a candidate at all. There is no stated support for Docusaurus 2 in the table.

The test script in package.json is literally `echo 'No Tests Found'`. There is no automated test suite in this repository. For a theme that renders a search modal and talks to a network service, that is worth knowing before you file a bug: the maintainers have no regression net here, and the README directs questions to GitHub issues rather than to any documented support channel.

Finally, the README does not document rollback, offline behaviour, or what the UI does when the Typesense endpoint errors. Those behaviours are inherited from the fork and the adapter, and this repository is silent on them.

## When a local or hosted search plugin is the better fit

The closest alternative in kind is EasyOps-cn/docusaurus-search-local, which builds an index from your Markdown at build time and ships it with the site. The difference is not cosmetic. Local search has no server, no scraper, no query latency over the network, and it keeps working when your infrastructure does not. Its weakness is scale and relevance tuning: the index is whatever the plugin can extract from your content, and you cannot re-rank it with a search engine's features.

Algolia's own @docusaurus/theme-search-algolia is the other comparison, and it is the direct ancestor of this project. Choosing it means someone else runs the crawler and the cluster, and you pay for that convenience in control and, above a free tier, in money. Choosing docusaurus-theme-search-typesense means the opposite trade: you own the index and the uptime.

A third option, docusaurus-lunr-search, follows the local-index approach as well. If your documentation is a few hundred pages and your readers are mostly on fast connections, the local plugins are simpler to operate. This theme earns its keep when your corpus is large enough that a client-side index becomes a download problem, or when you already run Typesense for other parts of your product.

## Maintenance, versioning and licence

The repository is not archived, and the last push was on 2026-08-26, the same date as the v0.27.0 release. The release history shows a steady but unhurried cadence: v0.26.0 in November 2025, v0.27.0 in August 2026. The version numbers track the Docusaurus compatibility table rather than any independent feature roadmap, so an upgrade of this package is usually a response to a Docusaurus upgrade, not the other way round. Budget for that: when Docusaurus moves, this theme moves after it, and the compatibility table is where you find out whether your pair is supported.

The licence is MIT, stated in the README and in package.json. That is permissive and compatible with commercial documentation sites. Note only that this is a fork of a Docusaurus package, which is itself permissively licensed, so the fork inherits a clean lineage. Nothing here constitutes legal advice; if your organisation has licence review requirements, the MIT text in the repository is the document to check.

## Conclusion

Adopt docusaurus-theme-search-typesense if you run Docusaurus 3.9.x or later on Node 20 or newer and want the DocSearch interface backed by a Typesense cluster you control, and you are prepared to run the DocSearch scraper as a separate pipeline. Do not adopt it if you want a search index built from your Markdown at build time with no external service: EasyOps-cn/docusaurus-search-local or docusaurus-lunr-search fit that job, and Algolia's own theme remains the option if you would rather not operate a search backend at all. Before committing, verify three things against your own site: that your Docusaurus version falls inside the range in the compatibility table, that you have somewhere to run the scraper documented at typesense.org/docs/guide/docsearch.html, and what happens to search during a Typesense outage, because the theme queries a live endpoint rather than a static index.

## FAQ

### What is Typesense used for in docusaurus-theme-search-typesense?

It is the search engine behind the theme. The README describes Typesense as an open source search engine that is simple to use, run and scale, and positions it as an open source alternative to Algolia. In this package it stores the scraped documentation records that the DocSearch-style UI queries.

### Is Typesense free to use with this Docusaurus theme?

The theme package itself is MIT licensed, so there is no cost to install it. Typesense is described in the README as open source, but the documentation does not state hosting or pricing terms for a Typesense cluster, so where you run it and what that costs is outside what this repository documents.

### Which Docusaurus versions does docusaurus-theme-search-typesense support?

The README's compatibility table lists 0.27.x against Docusaurus >= 3.9.0 < 4.0.0 with Node >=20, 0.26.x against Docusaurus 3.9.x, 0.25.x against 3.8.x, and 0.24.x against 3.7.x. Node 18 is still allowed on the 0.24.x and 0.25.x lines.

### Does docusaurus-theme-search-typesense index my documentation by itself?

No. The README points to the Typesense DocSearch guide for setting up the DocSearch scraper first, then installing this plugin, so the crawl is a separate step. The repository contains no build-time indexing hook, which means the index stays current only if you re-run the scraper.

### What is the closest alternative to docusaurus-theme-search-typesense?

Algolia's @docusaurus/theme-search-algolia is the package this one forks, and it keeps the crawl and the index on Algolia's side. If you would rather have no external service at all, EasyOps-cn/docusaurus-search-local and docusaurus-lunr-search build an index from your content instead of querying a cluster.

## Sources

- [Official documentation](https://typesense.org/docs/guide/docsearch.html)
- [Official README](https://github.com/typesense/docusaurus-theme-search-typesense#readme)
- [Project repository](https://github.com/typesense/docusaurus-theme-search-typesense)
- [Release notes](https://github.com/typesense/docusaurus-theme-search-typesense/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/typesense-docusaurus-theme-search-typesense