Skip to main content
The searchLibrary method finds libraries matching your search query and library name, ranked by relevance to your specific use case.

​
Method Signature

// Returns JSON array (default)
await client.searchLibrary(
  query: string,
  libraryName: string,
  options?: SearchLibraryOptions
): Promise<Library[]>

// Returns formatted text
await client.searchLibrary(
  query: string,
  libraryName: string,
  options: SearchLibraryOptions & { type: 'txt' }
): Promise<string>

​
Parameters

​
query
string
required
The user’s question or task description. This is used for relevance ranking to return the most appropriate library matches.Examples:
  • "I need to build a REST API"
  • "Building a dashboard with charts"
  • "State management for React app"
​
libraryName
string
required
The name of the library to search for. This doesn’t need to be an exact match.Examples:
  • "react"
  • "express"
  • "typescript"
​
options
SearchLibraryOptions
Configuration options for the search request

​
Return Types

​
JSON Format (Default)

Returns an array of Library objects:
​
Library[]
array
Array of matching libraries, ordered by relevance

​
Text Format

Returns a formatted string with library information ready for display or LLM consumption.

​
Examples

​
Basic Search (JSON)

Search for React libraries and get structured data: 
import { Context7 } from '@upstash/context7-sdk';

const client = new Context7({ apiKey: 'ctx7sk-...' });

const libraries = await client.searchLibrary(
  'I want to build a user interface',
  'react'
);

console.log(`Found ${libraries.length} libraries`);

libraries.forEach(lib => {
  console.log(`Name: ${lib.name}`);
  console.log(`ID: ${lib.id}`);
  console.log(`Description: ${lib.description}`);
  console.log(`Snippets: ${lib.totalSnippets}`);
  console.log(`Quality: ${lib.benchmarkScore}/100`);
  console.log('---');
});

​
Explicit JSON Format

const libraries = await client.searchLibrary(
  'I need a web framework',
  'express',
  { type: 'json' }
);

// TypeScript knows this is Library[]
const firstLibrary = libraries[0];
console.log(firstLibrary.id); // e.g., "/expressjs/express"

​
Text Format for LLMs

Get pre-formatted text suitable for feeding to language models: 
const librariesText = await client.searchLibrary(
  'I want to use TypeScript',
  'typescript',
  { type: 'txt' }
);

// Use in your LLM prompt
const prompt = `
Available libraries:
${librariesText}

Which library should I use for ${userQuestion}?
`;

​
Filtering by Quality

Find high-quality libraries based on benchmark scores: 
const libraries = await client.searchLibrary(
  'state management for React',
  'redux'
);

const highQuality = libraries.filter(lib => lib.benchmarkScore > 80);

console.log(`Found ${highQuality.length} high-quality libraries`);

​
Library Discovery UI

Build a library selection interface: 
async function findLibraries(userTask: string, searchTerm: string) {
  const libraries = await client.searchLibrary(userTask, searchTerm);
  
  return libraries.map(lib => ({
    value: lib.id,
    label: lib.name,
    description: lib.description,
    badges: [
      `${lib.totalSnippets} docs`,
      `Quality: ${lib.benchmarkScore}/100`
    ]
  }));
}

// Usage in UI framework
const options = await findLibraries(
  'Build a REST API with Node.js',
  'express'
);

​
Comparing Multiple Libraries

const searchTerms = ['react', 'vue', 'svelte'];

const results = await Promise.all(
  searchTerms.map(term =>
    client.searchLibrary('I want to build a web app', term)
  )
);

// Compare the top result from each
results.forEach((libs, index) => {
  if (libs.length > 0) {
    const top = libs[0];
    console.log(`${searchTerms[index]}: ${top.benchmarkScore}/100`);
  }
});

​
Error Handling

import { Context7Error } from '@upstash/context7-sdk';

try {
  const libraries = await client.searchLibrary(
    'Build a web app',
    'react'
  );
  
  if (libraries.length === 0) {
    console.log('No libraries found');
  }
} catch (error) {
  if (error instanceof Context7Error) {
    console.error('Context7 error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Empty Query Validation

try {
  // This will throw an error
  const libraries = await client.searchLibrary('', '');
} catch (error) {
  if (error instanceof Context7Error) {
    console.error('Invalid search parameters');
  }
}

​
Type Definitions

​
SearchLibraryOptions

interface SearchLibraryOptions {
  /**
   * Response format
   * - "json": Returns Library[] array (default)
   * - "txt": Returns formatted text string
   */
  type?: 'json' | 'txt';
}

​
Library

interface Library {
  /** Context7 library ID (e.g., "/facebook/react") */
  id: string;
  
  /** Library display name */
  name: string;
  
  /** Library description */
  description: string;
  
  /** Number of documentation snippets available */
  totalSnippets: number;
  
  /** Source reputation score (0-10) */
  trustScore: number;
  
  /** Quality indicator score (0-100) */
  benchmarkScore: number;
  
  /** Available versions/tags */
  versions?: string[];
}

​
Best Practices

​
Write Descriptive Queries

Better queries lead to more relevant results: 
// Less effective
await client.searchLibrary('react', 'react');

// More effective - provides context
await client.searchLibrary(
  'I need to build a dashboard with real-time updates',
  'react'
);

​
Use Quality Scores

Consider both trust and benchmark scores when selecting libraries: 
const libraries = await client.searchLibrary(query, searchTerm);

const best = libraries.find(lib => 
  lib.trustScore > 8 && lib.benchmarkScore > 75
);

​
Cache Results

For repeated searches, consider caching results: 
const cache = new Map<string, Library[]>();

async function cachedSearch(query: string, libraryName: string) {
  const key = `${query}:${libraryName}`;
  
  if (cache.has(key)) {
    return cache.get(key)!;
  }
  
  const results = await client.searchLibrary(query, libraryName);
  cache.set(key, results);
  
  return results;
}

​
Next Steps

Get Documentation Context

Learn how to retrieve documentation snippets for a specific library

Build docs developers (and LLMs) love

Get started for freeTalk to us