cossette-instantsearch-kit

Svelte 5 InstantSearch widgets and a SvelteKit SSR adapter — a port of react-instantsearch + react-instantsearch-nextjs.

Not affiliated with Algolia.

Install

npm install cossette-instantsearch-kit algoliasearch instantsearch.css

Peer deps: svelte ^5, @sveltejs/kit ^2.

Quick start (SvelteKit + SSR)

<!-- src/routes/search/Search.svelte -->
<script lang="ts">
  import { liteClient as algoliasearch } from 'algoliasearch/lite';
  import {
    InstantSearchKit,
    SearchBox,
    Hits,
    Highlight,
    Pagination
  } from 'cossette-instantsearch-kit';

  const searchClient = algoliasearch('APP_ID', 'SEARCH_API_KEY');
</script>

<InstantSearchKit indexName="your_index" routing {searchClient}>
  <SearchBox placeholder="Search" />

  <Hits>
    {#snippet hit({ hit })}
      <Highlight attribute="name" {hit} />
    {/snippet}
  </Hits>

  <Pagination />
</InstantSearchKit>

// src/routes/search/+page.server.ts
import { getServerState } from 'cossette-instantsearch-kit';
// Important: pass a regular component, not `+page.svelte`
import Search from './Search.svelte';

export const load = ({ url }) => getServerState(Search, url);

<!-- src/routes/search/+page.svelte -->
<script lang="ts">
  import Search from './Search.svelte';
</script>

<Search />

InstantSearchKit is the SvelteKit equivalent of InstantSearchNext:

• hydrates initialResults from getServerState / page.data
• wires routing to SvelteKit replaceState + history

Without the Kit helper

<script lang="ts">
  import { InstantSearch, SearchBox, Hits } from 'cossette-instantsearch-kit';
</script>

<InstantSearch indexName="your_index" {searchClient} routing>
  <SearchBox />
  <Hits />
</InstantSearch>

Custom connectors

<script lang="ts">
  import { connect } from 'cossette-instantsearch-kit';
  import { connectStats } from 'instantsearch.js/es/connectors';

  const state = connect(connectStats, {}, { $$widgetType: 'svelte-instantsearch.stats' });
  let { nbHits } = $derived($state);
</script>

<p>{nbHits} results</p>

Widgets

SearchBox, Hits, InfiniteHits, Highlight, Snippet, Pagination, RefinementList, Menu, HierarchicalMenu, Breadcrumb, CurrentRefinements, ClearRefinements, ToggleRefinement, RangeInput, SortBy, HitsPerPage, Stats, PoweredBy, Configure, Index.

Develop

nvm use   # Node 24
npm install
npm run dev

Releases

Publishing is automated via npm Trusted Publishing (GitHub OIDC — no long-lived npm token). Pushing a v* tag runs CI → npm publish.

# 1. Land your changes on main
git checkout main && git pull

# 2. Bump version (creates commit + tag, e.g. v0.1.1)
npm version patch   # or minor / major

# 3. Push commit + tag — CI publishes to npm
git push && git push --tags

One-time: trusted publisher on npm

1. Open the package on npmjs.com → Package Settings → Trusted Publisher
2. Choose GitHub Actions and set:
   • Organization or user: cossette-numerique
   • Repository: cossette-instantsearch-kit
   • Workflow filename: publish.yml (filename only, not the path)
   • Allowed actions: include npm publish
3. Save

If the package doesn’t exist yet, publish once from your machine (with 2FA), then add the trusted publisher, or create the empty package on npm first.

You can remove the NPM_TOKEN GitHub secret if you added one earlier — it’s unused now.

License

MIT