Contributing Guide - LlamaIndex.TS

Thank you for your interest in contributing to LlamaIndex.TS! We welcome contributions from everyone, whether you’re fixing a bug, adding a feature, or improving documentation.

Getting Started

Prerequisites

Before you begin, make sure you have:

Node.js LTS (Long-term Support) installed
pnpm package manager
Git for version control
Basic understanding of TypeScript and Node.js

Check your versions:

node -v   # Should be v20.x or v22.x
pnpm -v   # Latest version recommended

Install pnpm

If you don’t have pnpm installed:

npm install -g pnpm

Fork and Clone

Fork the repository on GitHub
Clone your fork:

git clone https://github.com/YOUR_USERNAME/LlamaIndexTS.git
cd LlamaIndexTS

Add upstream remote:

git remote add upstream https://github.com/run-llama/LlamaIndexTS.git

Project Structure

LlamaIndex.TS uses a pnpm monorepo structure:

LlamaIndexTS/
├── packages/
│   ├── llamaindex/          # Main package
│   ├── core/                # Core abstractions and interfaces
│   ├── env/                 # Environment-specific compatibility
│   ├── providers/           # Provider packages (LLMs, vector stores)
│   │   ├── openai/
│   │   ├── anthropic/
│   │   ├── storage/pinecone/
│   │   └── ...
│   ├── workflow/            # Workflow and agent orchestration
│   ├── tools/               # Function calling tools
│   └── readers/             # File format readers
├── examples/                # Usage examples
├── e2e/                     # End-to-end tests
└── apps/
    └── next/                # Documentation website

Key Directories

packages/llamaindex: The main package that aggregates core functionality
packages/core: Abstract base classes and interfaces for runtime-agnostic code
packages/env: Runtime compatibility layers for different JS environments
packages/providers/*: Separate packages for LLMs, embeddings, vector stores, etc.

Development Setup

1. Install Dependencies

pnpm install
pnpm install -g tsx  # For running TypeScript files

2. Build Packages

pnpm build

This builds all packages using Turbo for efficient parallel builds.

3. Start Development Mode

pnpm dev

This runs all packages in watch mode, automatically rebuilding on changes. To watch specific packages:

pnpm turbo run dev --filter="./packages/core" --concurrency=100

Making Changes

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Your Changes

Edit the relevant files in the appropriate package. Quick testing: Create a test script to verify your changes:

// test-script.ts
import { VectorStoreIndex } from "llamaindex";
import { OpenAI } from "@llamaindex/openai";

// Your test code here

Run it with:

pnpm exec tsx test-script.ts

3. Add Tests

All new features and bug fixes should include tests. Unit tests are located in each package’s tests/ folder:

// packages/core/tests/my-feature.test.ts
import { describe, it, expect } from "vitest";

describe("MyFeature", () => {
  it("should work correctly", () => {
    expect(true).toBe(true);
  });
});

Run tests:

pnpm test

Run tests for a specific package:

turbo run test --filter="@llamaindex/core"

4. Run Linting

pnpm lint

Auto-fix issues:

pnpm format:write

5. Type Check

pnpm type-check

Adding a New Package

When to Create a New Package

Adding a new LLM provider (e.g., @llamaindex/mistral)
Adding a new vector store (e.g., @llamaindex/storage/milvus)
Adding a new reader or tool

Steps

Create the package in packages/providers/:

mkdir -p packages/providers/my-provider

Use existing package.json as a template:

{
  "name": "@llamaindex/my-provider",
  "version": "0.0.1",
  "type": "module",
  "dependencies": {
    "@llamaindex/core": "workspace:*"
  },
  "scripts": {
    "build": "bunchee",
    "dev": "bunchee --watch"
  }
}

Reference in root tsconfig.json:

{
  "references": [
    { "path": "./packages/providers/my-provider" }
  ]
}

Add to examples if applicable:

// examples/package.json
{
  "dependencies": {
    "@llamaindex/my-provider": "workspace:*"
  }
}

Submitting a Pull Request

Before Submitting

All tests pass:

pnpm build
pnpm test
pnpm lint
pnpm type-check

Create a changeset for version bumping:

pnpm changeset

You’ll be prompted to:

Select which packages changed
Choose bump type (major, minor, patch)
Write a description of the changes

Submit Your PR

Push your branch:

git push origin feature/your-feature-name

Open a Pull Request on GitHub with:
- Clear title describing the change
- Description of what changed and why
- Reference any related issues
- Screenshots/examples if applicable
Address review feedback:
- Make requested changes
- Push additional commits
- Re-request review when ready

PR Checklist

Tests added/updated and passing
Documentation updated (if needed)
Examples added/updated (for new features)
Changeset created
Code follows existing style
No breaking changes (or clearly documented)

Documentation

If your changes affect user-facing APIs:

Update the docs in apps/next/ folder
Add examples in the examples/ folder
Update README if adding a new package

Code Style

Formatting

We use Prettier for formatting. It runs automatically on commit via Husky. Manual formatting:

pnpm format:write

Linting

We use ESLint. Configuration is in eslint.config.js.

pnpm lint

TypeScript

Use strict mode
Prefer interfaces over types for public APIs
Add JSDoc comments for public APIs
Use async/await instead of promises

Example:

/**
 * Creates a vector store index from documents.
 *
 * @param documents - Array of documents to index
 * @param options - Optional configuration
 * @returns The created vector store index
 */
export async function createIndex(
  documents: Document[],
  options?: IndexOptions,
): Promise<VectorStoreIndex> {
  // Implementation
}

Testing

Unit Tests

Use Vitest for unit tests:

import { describe, it, expect } from "vitest";

describe("MyComponent", () => {
  it("should handle edge cases", () => {
    // Test implementation
  });
});

E2E Tests

End-to-end tests are in the e2e/ folder and test runtime compatibility:

pnpm e2e

Running Tests

# All tests
pnpm test

# Specific package
turbo run test --filter="@llamaindex/core"

# Watch mode
pnpm test --watch

Common Tasks

Check for Circular Dependencies

pnpm circular-check

Clean Build Artifacts

pnpm clean

Update Dependencies

pnpm update --latest

Release Process (Maintainers)

We use Changesets for versioning and releases:

PRs are merged with changesets
Release PR is auto-generated
Merging release PR publishes to npm

Manual release (maintainers only):

pnpm release

Getting Help

If you need help contributing:

Discord: Join our Discord
GitHub Discussions: Ask a question
Issues: Open an issue

Code of Conduct

Please be respectful and inclusive. We’re building a welcoming community for everyone.

Thank You!

Your contributions make LlamaIndex.TS better for everyone. We appreciate your time and effort!

Community

Join our community to connect with other contributors

Migration Guides

Resources

​Getting Started

​Prerequisites

​Install pnpm

​Fork and Clone

​Project Structure

​Key Directories

​Development Setup

​1. Install Dependencies

​2. Build Packages

​3. Start Development Mode

​Making Changes

​1. Create a Branch

​2. Make Your Changes

​3. Add Tests

​4. Run Linting

​5. Type Check

​Adding a New Package

​When to Create a New Package

​Steps

​Submitting a Pull Request

​Before Submitting

​Submit Your PR

​PR Checklist

​Documentation

​Code Style

​Formatting

​Linting

​TypeScript

​Testing

​Unit Tests

​E2E Tests

​Running Tests

​Common Tasks

​Check for Circular Dependencies

​Clean Build Artifacts

​Update Dependencies

​Release Process (Maintainers)

​Getting Help

​Code of Conduct

​Thank You!