~7 kB gzipped · zero dependencies

MiniSearch

Lekka biblioteka do wyszukiwania pełnotekstowego w przeglądarce. Prefix, fuzzy, boosting, filtry, podpowiedzi — wszystko po stronie klienta, błyskawicznie.

200 dok. zaindeksowanych 209 ms czas indeksowania 4 kategorie

Interaktywny plac zabaw

Wyszukuj w zbiorze dokumentacji MiniSearch w czasie rzeczywistym.

Alt + Shift + M — przejdź do wyszukiwarki

Indeksowanie na żywo

Dodawaj, zamieniaj i usuwaj dokumenty w locie — od razu widać efekt w wynikach.

Dodaj / zamień dokument

Operacje wsadowe

Import z pliku JSON

Wymagane pola: title (string), text (string), category (string). title (string), text (string). Opcjonalnie: tags (string[]). ID zostaną nadane automatycznie. tags (string[]), category (string).

Akceptuje: tablica JSON dokumentów

Usuwanie dokumentów

remove: usuwa dokument natychmiast z indeksu.

discard: oznacza jako usunięty, vacuum czyści później.

200Dokumenty
2157Unikalne terminy
0Brudne wpisy
0.0%Dirt factor

Snapshot indeksu (JSON)

Zapisz i odtwórz indeks bez reindeksacji (sync lub async).

Cache (trwały stan)

Zapisz aktualny indeks i opcje, a po odświeżeniu strony przywróć je jednym kliknięciem.

N-gram vs standard

Porównaj wyniki przy indeksowaniu standardowym i z n-gramami.

Szybka ściąga

Snippety i linki do dokumentacji dla wszystkich opcji playgroundu.

Tworzenie indeksu

import MiniSearch from 'minisearch';

const miniSearch = new MiniSearch({
  fields: ['title', 'text'],
  storeFields: ['title', 'category']
});

Dodawanie dokumentów

miniSearch.addAll([
  { id: 1, title: 'Angular', text: 'Frontend framework', category: 'frontend' },
  { id: 2, title: 'React', text: 'UI library', category: 'frontend' },
  { id: 3, title: 'Node.js', text: 'JS runtime', category: 'backend' },
]);

Podstawowe wyszukiwanie

const results = miniSearch.search('angular');
// => [{ id: 1, score: 1.38, match: { angular: ['title'] } }]

Wyszukiwanie rozmyte

// Tolerates typos (up to 20% of term length)
const results = miniSearch.search('anglar', { fuzzy: 0.2 });

Wyszukiwanie prefiksowe

// Prefix matching: match words starting with 'ang'
const results = miniSearch.search('ang', { prefix: true });

Wzmacnianie pól

const results = miniSearch.search('framework', {
  boost: { title: 2 } // title matches are 2x more important
});

Filtrowanie wyników

const results = miniSearch.search('search', {
  filter: (result) => result.category === 'frontend'
});

Podpowiedzi (autoSuggest)

const suggestions = miniSearch.autoSuggest('ang', { prefix: true });
// => [{ suggestion: 'angular', score: 5.2 }, ...]

Zapis / odtworzenie (JSON)

// Save
const json = JSON.stringify(miniSearch);

// Restore
const restored = MiniSearch.loadJSON(json, {
  fields: ['title', 'text']
});

Porównanie

FunkcjaMiniSearchLunr.jsFuse.jsFlexSearch
Rozmiar (gzip)~7 kB~8 kB~5 kB~6 kB
FuzzyTakTakTak (core)Tak
PrefixTakTakNieTak
Indeksowanie przyrostoweTakNie (rebuild)N/ATak
PodpowiedziWbudowaneNieNieNie
TF-IDF / scoringTakTakNie (Bitap)Nie
TypeScriptNatywnieTakTakCzęściowo

Zastosowania

Dokumentacja

Wyszukiwanie w dokumentacji w przeglądarce (online lub offline).

Autocomplete

Podpowiedzi w czasie rzeczywistym (autoSuggest).

Filtry po stronie klienta

Filtrowanie wyników bez backendu.

Offline

Działa bez sieci (wbudowany dataset).

Prototypowanie

Szybkie testy UX/search bez infrastruktury.

E-commerce

Wyszukiwarka produktów z rankingiem i filtrami.

Rozwiązania custom

MiniSearch jest mały, ale elastyczny. Możesz go dopasować do własnych danych i UI.

Podświetlenia

Renderuj dopasowania jako HTML (np. <mark>) i kontroluj, co trafia do [innerHTML].

Linki do dokumentów

Trzymaj URL w dokumencie i linkuj do oryginalnej strony bezpośrednio z wyników.

Wykres wydajności

Zbieraj czasy wyszukiwań i rysuj sparkline w SVG, żeby zobaczyć wpływ opcji na latency.

O MiniSearch

Lekki silnik wyszukiwania pełnotekstowego dla przeglądarki — zero zależności, ~7 kB gzipped, pełna kontrola po stronie klienta.

Czym jest MiniSearch?

MiniSearch to biblioteka wyszukiwania JavaScript stworzona przez Lucę Ongaro, zaprojektowana z myślą o wyszukiwaniu po stronie klienta bezpośrednio w przeglądarce użytkownika. W odróżnieniu od klasycznych rozwiązań, które wymagają serwera backendowego, dedykowanego silnika indeksującego czy zewnętrznej usługi w chmurze, MiniSearch działa w całości w środowisku JavaScript — czy to w przeglądarce, Node.js, Deno, czy Bun. Przy rozmiarze zaledwie około 7 kB po kompresji gzip i zerowej liczbie zewnętrznych zależności, jest to jeden z najlżejszych silników wyszukiwania pełnotekstowego dostępnych w ekosystemie JavaScript. Biblioteka realizuje wyszukiwanie pełnotekstowe z zaawansowanym scoringiem opartym na algorytmach TF-IDF oraz BM25, co oznacza, że wyniki są sortowane według trafności, a nie tylko prostego dopasowania ciągów znaków. MiniSearch oferuje wyszukiwanie rozmyte (fuzzy search) tolerujące literówki, wyszukiwanie prefiksowe umożliwiające autouzupełnianie w trakcie pisania, boosting pól pozwalający faworyzować dopasowania w ważniejszych polach dokumentu, oraz rozbudowane mechanizmy filtrowania wyników. Co istotne, MiniSearch ma pełne wsparcie dla TypeScript, dostarczając kompletne definicje typów, co czyni integrację z nowoczesnymi projektami Angular, React czy Vue bezproblemową. Filozofia biblioteki jest prosta: dać deweloperowi potężne narzędzie wyszukiwania bez narzutu infrastrukturalnego, opóźnień sieciowych i kosztów utrzymania zewnętrznych serwisów.

Kluczowe cechy

MiniSearch wyróżnia się imponującym zestawem funkcji, które sprawiają, że lekki silnik wyszukiwania staje się pełnoprawnym narzędziem produkcyjnym. Wyszukiwanie rozmyte (fuzzy search) automatycznie toleruje literówki i drobne błędy w pisowni — użytkownik wpisujący "angulr" zamiast "angular" wciąż otrzyma trafne wyniki. Wyszukiwanie prefiksowe pozwala na natychmiastowe autouzupełnianie: już po wpisaniu pierwszych liter zapytania pojawiają się podpowiedzi, co jest kluczowe dla nowoczesnych interfejsów wyszukiwania w przeglądarce. Mechanizm autoSuggest generuje inteligentne podpowiedzi na podstawie indeksu, co oznacza, że lista sugestii dynamicznie dostosowuje się do rzeczywistych danych, a nie statycznej listy słów kluczowych. Boosting pól umożliwia priorytetyzację dopasowań — na przykład dopasowanie w tytule dokumentu może mieć trzykrotnie większą wagę niż dopasowanie w treści. Filtrowanie wyników działa za pomocą callback functions, co daje pełną elastyczność: filtruj po kategorii, tagach, dacie, roli użytkownika lub dowolnym innym kryterium. Inkrementalne indeksowanie pozwala dodawać, usuwać i zamieniać dokumenty w locie, bez konieczności przebudowy całego indeksu. Wreszcie, tokenizacja N-gram umożliwia dopasowywanie podciągów (substring matching), co jest nieocenione przy wyszukiwaniu w środku słowa.

Jak to działa

Pod maską MiniSearch buduje odwrócony indeks (inverted index) — strukturę danych, która mapuje każdy termin (słowo) na listę dokumentów, w których się pojawia, wraz z informacją o pozycji i częstości występowania. Proces rozpoczyna się od tokenizacji: tekst dokumentu jest dzielony na tokeny (domyślnie po białych znakach), które następnie przechodzą przez pipeline przetwarzania terminów (processTerm). Na tym etapie można zastosować normalizację diakrytyków (zamiana ą na a, ć na c), rozwijanie synonimów, odrzucanie stop-words czy niestandardowe przekształcenia. Deweloper ma pełną kontrolę nad tym pipeline, mogąc zdefiniować osobne reguły dla indeksowania i wyszukiwania. Scoring wyników wykorzystuje algorytm BM25 — ulepszony wariant klasycznego TF-IDF, który lepiej radzi sobie z dokumentami o różnej długości. Parametry BM25 (k, b, d) są konfigurowalne, co pozwala dostroić ranking do specyfiki danych. Mechanizm extractField umożliwia indeksowanie pól zagnieżdżonych (np. metadata.author) oraz tworzenie pól pochodnych łączących informacje z wielu źródeł. Cały proces jest deterministyczny i przewidywalny — nie ma żadnych wywołań sieciowych, losowości ani zewnętrznych zależności. Indeks żyje w pamięci JavaScript, a zapytania są przetwarzane synchronicznie w nanosekundach.

Zastosowania w praktyce

Wyszukiwanie po stronie klienta z MiniSearch sprawdza się doskonale w wielu scenariuszach, gdzie tradycyjne rozwiązania serwerowe byłyby nadmiarowe lub niemożliwe do zastosowania. Najpopularniejszym przypadkiem użycia jest wyszukiwanie w dokumentacji technicznej — statyczne strony generowane przez narzędzia typu VitePress, Docusaurus czy Storybook mogą oferować błyskawiczne wyszukiwanie pełnotekstowe bez żadnego backendu. Aplikacje e-commerce wykorzystują MiniSearch do filtrowania katalogów produktów z autouzupełnianiem i rankingiem trafności, co drastycznie poprawia doświadczenie użytkownika. Wyszukiwanie offline to kolejna silna strona biblioteki: aplikacje PWA (Progressive Web Apps) mogą indeksować dane pobrane wcześniej i oferować pełne wyszukiwanie bez połączenia z internetem — idealne dla aplikacji terenowych, edukacyjnych czy medycznych działających w obszarach z ograniczonym dostępem do sieci. MiniSearch sprawdza się też jako silnik autouzupełniania w formularzach, wyszukiwarkach wewnętrznych paneli administracyjnych, narzędziach do zarządzania wiedzą (knowledge base) czy nawet grach przeglądarkowych z bazą danych przedmiotów. Dla zespołów deweloperskich jest to idealne narzędzie do prototypowania interfejsów wyszukiwania — można zbudować w pełni funkcjonalny prototyp bez konfigurowania Elasticsearch, Algolia czy Meilisearch, a następnie zdecydować, czy rozwiązanie klienckie wystarczy na produkcji.

Wydajność i szczegóły techniczne

Wydajność MiniSearch jest jednym z jej największych atutów. Indeksowanie tysięcy dokumentów zajmuje zazwyczaj kilkanaście do kilkudziesięciu milisekund, a pojedyncze zapytanie zwraca wyniki w ułamkach milisekundy. Dla większych zbiorów danych (dziesiątki tysięcy dokumentów) biblioteka oferuje addAllAsync — asynchroniczne indeksowanie w chunkach, które nie blokuje głównego wątku przeglądarki i utrzymuje interfejs responsywnym. Mechanizm snapshotów JSON to kolejna kluczowa cecha: cały indeks można zserializować do formatu JSON za pomocą jednego wywołania, zapisać w localStorage, IndexedDB lub przesłać na serwer, a następnie odtworzyć bez kosztownego reindeksowania. Funkcja loadJSON (oraz jej asynchroniczny wariant loadJSONAsync) przywraca indeks z migawki błyskawicznie, co jest idealne dla scenariuszy, gdzie indeks jest budowany po stronie serwera podczas deploymentu, a klient jedynie go ładuje. System vacuum zarządza wewnętrzną czystością indeksu: dokumenty oznaczone jako usunięte (discard) są leniwie czyszczone, co optymalizuje operacje masowego usuwania. BM25 scoring z konfigurowalnymi parametrami k (saturacja TF), b (normalizacja długości dokumentu) i d (składnik dla krótkich dokumentów) pozwala precyzyjnie dostroić ranking. Wagi (weights) dla dopasowań fuzzy i prefix dają dodatkową kontrolę nad kolejnością wyników. Całość działa bez Web Workers, choć nic nie stoi na przeszkodzie, by przenieść indeks do workera dla jeszcze lepszej wydajności.

Jak zacząć

Rozpoczęcie pracy z MiniSearch jest niezwykle proste. Wystarczy zainstalować bibliotekę poleceniem npm install minisearch (lub yarn add minisearch), a następnie zaimportować ją w projekcie. Tworzenie indeksu wymaga jedynie zdefiniowania pól do indeksowania i pól przechowywanych w wynikach. Minimalna konfiguracja to kilka linii kodu: new MiniSearch({ fields: ['title', 'text'], storeFields: ['title', 'category'] }), dodanie dokumentów przez miniSearch.addAll(documents) i wyszukiwanie przez miniSearch.search('zapytanie'). Od tego momentu można stopniowo dodawać zaawansowane funkcje: włączyć wyszukiwanie rozmyte (fuzzy: 0.2), wyszukiwanie prefiksowe (prefix: true), boosting pól (boost: { title: 2 }), filtrowanie (filter: fn) czy autouzupełnianie (miniSearch.autoSuggest('za')). Biblioteka ma doskonałą dokumentację na GitHubie (lucaong/minisearch) z przykładami dla każdej opcji. Ten Playground, na którym się znajdujesz, pozwala interaktywnie eksperymentować z każdą z tych funkcji — zmieniaj parametry, obserwuj wyniki w czasie rzeczywistym i buduj intuicję, zanim zaczniesz pisać własny kod. MiniSearch to wyszukiwanie w przeglądarce, które po prostu działa — od pierwszej linii kodu do produkcji.

Najlepsze wyszukiwanie to takie, które działa natychmiast, bez serwera, bez opóźnień, bez zależności — po prostu Twoje dane i Twój użytkownik, połączeni w ułamku milisekundy.