Migration from Vue InstantSearch
This page documents how Nuxt Swiftsearch reaches vue-instantsearch-like DX while preserving Nuxt SSR correctness.
1) Keep your component tree, switch the runtime
Most widget tags map 1:1 (AisSearchBox, AisHits, AisRefinementList, etc.).
Your primary change is at the root: Nuxt Swiftsearch owns the final widget registration to make SSR deterministic.
2) Start with declarative mode
If you omit :widgets on <AisInstantSearch>, the transform compiles template widgets into the same connector widgets you used to build manually.
<template>
<AisInstantSearch :configuration="configuration">
<AisSearchBox />
<AisRefinementList attribute="brand" />
<AisHits />
</AisInstantSearch>
</template>
3) Keep manual mode where needed
Manual mode remains first-class and interoperable:
- existing
:widgets="[...]"code keeps working, useAis*composables are unchanged,- you can mix manual pages and declarative pages in the same app.
4) Use indexId for multi-index boundaries
When multiple <AisIndex> instances use the same widget types, set index-id to ensure state isolation:
<AisInstantSearch :configuration="configuration">
<AisIndex index-name="instant_search" index-id="products">
<AisRefinementList attribute="brand" />
</AisIndex>
<AisIndex index-name="instant_search" index-id="accessories">
<AisRefinementList attribute="brand" />
</AisIndex>
</AisInstantSearch>
5) Widget-ID parity for repeated widgets
Repeated widgets that rely on explicit IDs (AisClearRefinements, AisCurrentRefinements, AisRefinementList, AisAutocomplete) now scope correctly per index and per widget ID.
Feature comparison
Comparison below is specifically about using these libraries in a Nuxt app.
| Capability | Nuxt Swiftsearch | Vue InstantSearch | Comparison |
|---|---|---|---|
| SSR behavior in Nuxt | Parent-owned widget graph, deterministic SSR/hydration flow | Client-first widget registration model | Better fit for Nuxt SSR |
| Declarative widget authoring | Supported (compile-time transform to :widgets) | Supported (runtime registration) | Equivalent DX goal, different architecture |
Existing manual :widgets mode | Fully supported | N/A (runtime declarative by default) | Migration-safe advantage |
| Multi-index scoped state | Explicit indexId + scoped widget IDs | Multi-index supported | Better isolation guarantees in this module |
| Nuxt router integration | useAisRouter() and custom routing patterns validated in playground | Routing integration is not there out-of-the-box, also its not working server side. | Better out-of-the-box for Nuxt |
| Parity validation | Dedicated fixture/e2e parity coverage in this repo | Upstream library behavior baseline | Swiftsearch is explicitly tested against Vue IS |
Remaining differences
| Area | Current Swiftsearch status | Vue InstantSearch |
|---|---|---|
AisInstantSearchSsr component | Not exposed separately; SSR is built into AisInstantSearch | Separate AisInstantSearchSsr component |
Some advanced dynamic declarative structures (v-for widgets) | Not transformed automatically; use manual :widgets mode | Supported by runtime component registration |
For a full widget-by-widget matrix against vue-instantsearch@4.24.3, see Widget Coverage & Upstream Audit.
Intentional differences
- SSR model is parent-owned by design.
AisInstantSearchSsrbehavior is merged intoAisInstantSearch.- Some advanced dynamic widget patterns are intentionally routed through manual mode for predictability.
:widgets only where you need custom runtime composition.