{"id":17993,"library":"vectra","title":"Vectra","description":"Vectra is a lightweight, local, file-backed, in-memory vector database designed for Node.js (v22.x+) and browser environments. Currently at version 0.14.0, it follows an active release cadence, introducing significant features and occasional breaking changes. Its key differentiators include operating entirely locally with a file-system backend (each index corresponds to a folder on disk), offering Pinecone-compatible metadata filtering, and integrating hybrid BM25 keyword search for advanced Retrieval-Augmented Generation (RAG) pipelines. The package also provides an optional gRPC server for cross-language access, comprehensive browser and Electron support via a dedicated `vectra/browser` entry point, and the capability to use local embeddings with HuggingFace models without requiring external API keys. Data storage can be optimized using Protocol Buffers for more compact files.","status":"active","version":"0.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/Stevenic/vectra","tags":["javascript","vector-database","embeddings","semantic-search","rag","retrieval-augmented-generation","openai","azure-openai","transformers","typescript"],"install":[{"cmd":"npm install vectra","lang":"bash","label":"npm"},{"cmd":"yarn add vectra","lang":"bash","label":"yarn"},{"cmd":"pnpm add vectra","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for using `TransformersEmbeddings` for local, client-side embedding generation.","package":"@huggingface/transformers","optional":true}],"imports":[{"note":"Primary class for managing local, file-backed vector indexes. Use named imports for ESM. For browser environments, import from 'vectra/browser'.","wrong":"const LocalDocumentIndex = require('vectra').LocalDocumentIndex;","symbol":"LocalDocumentIndex","correct":"import { LocalDocumentIndex } from 'vectra';"},{"note":"Configures embedding generation using the OpenAI API. All embedding providers are named exports from the main package entry point.","wrong":"import OpenAIEmbeddings from 'vectra/openai-embeddings';","symbol":"OpenAIEmbeddings","correct":"import { OpenAIEmbeddings } from 'vectra';"},{"note":"Provides local, client-side embedding generation using Hugging Face models. Requires `@huggingface/transformers` as a peer dependency.","wrong":"import { TransformersEmbeddings } from 'vectra/browser';","symbol":"TransformersEmbeddings","correct":"import { TransformersEmbeddings } from 'vectra';"},{"note":"Specific storage adapter for browser environments, leveraging IndexedDB. Must be imported from the 'vectra/browser' entry point.","wrong":"import { IndexedDBStorage } from 'vectra';","symbol":"IndexedDBStorage","correct":"import { IndexedDBStorage } from 'vectra/browser';"}],"quickstart":{"code":"import { LocalDocumentIndex, OpenAIEmbeddings } from 'vectra';\nimport { createHash } from 'crypto';\n\n// Ensure you have your OpenAI API key set in environment variables\nconst OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? '';\nif (!OPENAI_API_KEY) {\n  console.error('OPENAI_API_KEY environment variable is not set.');\n  process.exit(1);\n}\n\nasync function runVectorSearch() {\n  const docs = new LocalDocumentIndex({\n    folderPath: './my-vectra-index',\n    embeddings: new OpenAIEmbeddings({\n      apiKey: OPENAI_API_KEY,\n      model: 'text-embedding-3-small',\n      maxTokens: 8000\n    })\n  });\n\n  // Check if the index exists, create it if not\n  if (!(await docs.isIndexCreated())) {\n    await docs.createIndex({ version: 1 });\n    console.log('New vector index created.');\n  }\n\n  // Generate a unique ID for the document\n  const docContent = 'Vectra is a local, file-backed, in-memory vector database with optional gRPC.';\n  const docId = `doc://${createHash('sha256').update(docContent).digest('hex')}`;\n\n  // Upsert a document into the index\n  await docs.upsertDocument(docId, docContent, 'txt');\n  console.log(`Document '${docId}' upserted.`);\n\n  // Query the index\n  const results = await docs.queryDocuments('What is Vectra?', { maxDocuments: 2 });\n\n  if (results.length > 0) {\n    console.log('Query Results:');\n    for (const result of results) {\n      console.log(`  Document: ${result.documentId}, Score: ${result.score}`);\n      const sections = await result.renderSections(2000, 1, true);\n      if (sections.length > 0) {\n        console.log(`    Content: ${sections[0].text.substring(0, 100)}...`);\n      }\n    }\n  } else {\n    console.log('No results found.');\n  }\n}\n\nrunVectorSearch().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to initialize a `LocalDocumentIndex`, ensure its creation, upsert a document, and perform a semantic search using OpenAI embeddings in Node.js. It includes necessary environment variable checks for API keys."},"warnings":[{"fix":"Replace `axios`-specific configurations with `requestConfig` (a `RequestInit` object) on embedding provider options, e.g., `new OpenAIEmbeddings({ ..., requestConfig: { headers: { 'Authorization': 'Bearer ...' } } })`.","message":"Vectra `v0.14.0` removed `axios` in favor of the built-in `fetch()` API for all HTTP requests. Projects that relied on `axios` interceptors or custom `axios` configurations must now migrate to using the `requestConfig` option (which accepts a standard `RequestInit` object) when configuring `OpenAIEmbeddings` or other HTTP-based embedding providers.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Ensure your development and deployment environments are running Node.js 22.x or later. Use a Node Version Manager (e.g., `nvm`) to update: `nvm install 22 && nvm use 22`.","message":"As of `v0.14.0`, the minimum required Node.js version is 22.x (previously 20.x). This change is primarily driven by updated dependencies, specifically `undici@8.0.0`, which mandates `node >=22.19.0`.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Always check for index existence with `await docs.isIndexCreated()` and conditionally call `await docs.createIndex({ version: 1 })` before interacting with the index, especially in application startup logic.","message":"When initializing a new `LocalDocumentIndex`, it must be explicitly created using `await docs.createIndex()` if it does not already exist. Failing to do so will result in runtime errors when attempting to upsert or query documents.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Change your imports from `import { Symbol } from 'vectra';` to `import { Symbol } from 'vectra/browser';` when targeting browser or Electron environments.","message":"For browser-based applications, the `vectra/browser` entry point must be used. Attempting to import from the main `vectra` package will likely result in Node.js-specific dependencies failing or not being properly bundled.","severity":"gotcha","affected_versions":">=0.14.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 22.x or higher. For example, using nvm: `nvm install 22 && nvm use 22`.","cause":"Running Vectra with an outdated Node.js version, typically 20.x or earlier, after upgrading Vectra to v0.14.0 or later.","error":"Error: Minimum Node.js version is 22.x"},{"fix":"Use ES module `import` syntax: `import { LocalDocumentIndex } from 'vectra';`. If strictly using CommonJS, ensure proper destructuring: `const { LocalDocumentIndex } = require('vectra');`.","cause":"Attempting to import `LocalDocumentIndex` (or other named exports) using CommonJS `require()` syntax without destructuring, or in an environment that expects ESM.","error":"TypeError: LocalDocumentIndex is not a constructor"},{"fix":"Ensure `process.env.OPENAI_API_KEY` is set in your environment, or pass the API key directly in the `OpenAIEmbeddings` constructor: `new OpenAIEmbeddings({ apiKey: 'your-api-key' })`.","cause":"The `apiKey` option for `OpenAIEmbeddings` was not provided or the `OPENAI_API_KEY` environment variable was not set.","error":"Error: OpenAI API key is missing. Please set the OPENAI_API_KEY environment variable."},{"fix":"Ensure you are using Node.js v22.x or higher (due to Vectra's requirements) which has `fetch` built-in. If you encounter this in a very specific environment, consider explicitly polyfilling `fetch` if Node.js v22.x is not an option (though it's required by Vectra v0.14+).","cause":"Occurs in older Node.js versions (pre-18) where `fetch` is not global, or if a browser environment is misconfigured to use a Node.js-specific polyfill that conflicts, or when an embedding provider expected `axios` but now uses `fetch`.","error":"TypeError: fetch is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}