Skip to main content
Introducing packages.sweber.dev
Documentation menuMigrating from Algolia

Migrating from Algolia

Turn an Algolia DocSearch export into a Cosine index without crawling your site again.

@weber-development/cosine-migrate converts the records and synonyms you export from Algolia into a Cosine index. The search then runs in the browser, without an account, a server or an API key.

npm i -D @weber-development/cosine-migrate
npx cosine-migrate algolia --records records.json --synonyms synonyms.json --out public/cosine

<cosine-search index="/cosine/cosine-index.json"></cosine-search>

Export from Algolia

In the Algolia dashboard open your index and use Manage index → Export, or browse the index with the API. Cosine reads a JSON array, an object with a hits array, or NDJSON. Synonyms come from Configuration → Synonyms.

How records become pages

DocSearch stores one record per heading or paragraph. The tool groups them by page URL, then:

  • hierarchy.lvl1 becomes the page title.
  • lvl2 and deeper become ## to #### headings, with the anchor from the URL hash, so results link to the exact section.
  • Content records become the text under their heading, in the order of weight.position.
  • Flat hierarchy_lvl0 keys work like the nested form.

URLs are reduced to path and hash, so the same index works on staging and production. --keep-origin keeps the domain.

Synonyms

AlgoliaCosine
synonym (several words that mean the same)one synonym group
oneWaySynonymone group of the input and its synonyms
placeholder, altCorrectiondropped

The command prints how many groups were converted and how many were dropped.

Options

OptionDefault
--records <file>Export from Algolia. Required
--synonyms <file>Synonyms export
--out <dir>public/cosineOutput directory
--keep-originoffKeep the domain in URLs
--lang <code>allOnly records of this language
--model <id>englishenglish, multilingual or a Hugging Face model id
--lexical-onlyoffNo embeddings, keyword search only
--incrementaloffReuse the vectors of the index already in --out
--boost <path=n>Rank results below a path higher or lower, repeatable

From code

import { migrateFromAlgolia } from "@weber-development/cosine-migrate";

const result = await migrateFromAlgolia({
  records: "records.json",
  synonyms: "synonyms.json",
  out: "public/cosine",
});
console.log(result.pages, result.records, result.synonyms);

records and synonyms accept a file path or the parsed array.

After the migration

Algolia's ranking rules and facets are not copied. Use boost for sections that should rank higher, and facets on the search element to filter by path. Once the new search works, remove the DocSearch script and delete the Algolia index.