Skip to content

Quick start

Get up and running in a few minutes with JavaScript or React.

JavaScript (core API)

1. Install and import

npm install vecnest

import { VecnestDB } from 'vecnest';

2. Connect and add text

const db = new VecnestDB('my-app-db');
await db.connect();

// Add documents (text is embedded via Transformers.js, then stored)
await db.addText('Vecnest stores vectors in IndexedDB.', { source: 'intro' });
await db.addText('Transformers.js embeds text in the browser.', { source: 'intro' });
await db.addText('Cosine similarity finds nearest vectors.', { source: 'intro' });

3. Search by text

const results = await db.searchText('Where are vectors stored?', { k: 5 });

for (const r of results) {
  console.log(r.metadata.text, '—', r.score.toFixed(4));
}

4. Close when done

db.close();

Full example

import { VecnestDB } from 'vecnest';

async function main() {
  const db = new VecnestDB('quickstart-db');
  await db.connect();

  await db.addText('Machine learning is a subset of AI.', { source: 'doc1' });
  await db.addText('Neural networks learn from data.', { source: 'doc2' });

  const results = await db.searchText('What is ML?', { k: 5 });
  console.log(results); // [{ id, score, metadata }, ...]

  db.close();
}

main().catch(console.error);

React (hooks)

1. Install Vecnest and React

npm install vecnest react react-dom

2. Use hooks

import { useState } from 'react';
import { useVecnest, useSearchText } from 'vecnest/react';

function SearchApp() {
  const { db, loading, error } = useVecnest('my-app-db');
  const [query, setQuery] = useState('');
  const { results, loading: searchLoading } = useSearchText(db, query, { k: 5 });

  if (loading) return <p>Loading…</p>;
  if (error) return <p role="alert">Error: {error.message}</p>;
  if (!db) return null;

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search…"
        aria-busy={searchLoading}
      />
      {searchLoading && <span aria-live="polite">Searching…</span>}
      <ul>
        {results.map((r) => (
          <li key={r.id}>
            {r.metadata?.text ?? '(no text)'} — {r.score.toFixed(4)}
          </li>
        ))}
      </ul>
    </div>
  );
}
  • useVecnest(dbName) — Opens the DB, returns { db, loading, error }. Closes on unmount.
  • useSearchText(db, queryText, opts) — Embeds the query, runs search, returns { results, loading, error }.

Optional: Vecnest UI (inspector)

To inspect DBs, documents, and 3D embeddings in your app, run npx vecnest setup-ui from your project root, add a link <a href="/vecnest-ui/index.html">Open Vecnest UI</a>, then run your dev server. See Vecnest UI setup for the full flow, RAG examples, and Webpack/Rollup notes.

Next steps