CONTRIBUTING.md

Contributing

Structure

LlamaIndex.TS uses pnpm monorepo.

We recommend you to understand the basics of Node.js, TypeScript, pnpm, and of course, LLM before contributing.

There are some important folders in the repository:

• packages/*: Contains the source code of the packages. Each package is a separate npm package.
  • llamaindex: The starter package for LlamaIndex.TS, which contains the all sub-packages.
  • core: The core package of LlamaIndex.TS, which contains the abstract classes and interfaces. It is designed for all JS runtime environments.
  • env: The environment package of LlamaIndex.TS, which contains the environment-specific classes and interfaces. It includes compatibility layers for Node.js, Deno, Vercel Edge Runtime, Cloudflare Workers...
  • providers/*: The providers package of LlamaIndex.TS, which contains the providers for LLM and other services.
• apps/*: The applications based on LlamaIndex.TS.
  • next: Our documentation website based on Next.js.
• examples: The code examples of LlamaIndex.TS using Node.js.

Getting Started

Make sure you have Node.js LTS (Long-term Support) installed. You can check your Node.js version by running:

node -v
# v22.x.x

Use pnpm

npm install -g pnpm

Install dependencies

pnpm install
pnpm install -g tsx

Build the packages

To build all packages, run:

pnpm build

Start Developing

You can launch the package in dev-mode by running:

pnpm dev

This will use turbo to run all packages in watch-mode. This means you can make changes and have them automatically built.

If you want to customize what packages are built/watched, you can run turbo directly and adjust the filter:

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

In another terminal, you can write and run any script needed to quickly test your changes. For example:

import { createMemory, staticBlock } from "@llamaindex/core/memory";

// Create memory with predefined context
const memory = createMemory({
  memoryBlocks: [
    staticBlock({
      content:
        "The user is a software engineer who loves TypeScript and LlamaIndex.",
      messageRole: "system",
    }),
  ],
});

async function main() {
  const result = await memory.getLLM();
  console.log(result);
}

void main().catch(console.error);

And run it with:

pnpm exec tsx my_script.ts

This flow allows you to easily test your changes without having to build the entire project.

Once you are happy with your changes, be sure to add tests (and confirm existing tests are passing!).

Run tests

Unit tests

After build, to run all unit tests, call:

pnpm test

Unit tests are located in the tests folder of each package. They are using their own package (e.g. @llamaindex/core-tests for @llamaindex/core). The tests are importing the package under test and the test package is not published.

E2E tests

To run all E2E tests, call:

pnpm e2e

All E2E tests are in the e2e folder.

Docs

See the docs for more information.

Adding a new package

Please follow these steps to add a new package:

1. Only add new packages to the packages/providers folder.
2. Use the package.json and tsconfig.json of an existing packages as template.
3. Reference your new package in the root tsconfig.json file
4. Add your package to the examples/package.json file if you add a new example.

Before sending a PR

Before sending a PR, make sure of the following:

1. Tests are all running and you added meaningful tests for your change.
2. If you have a new feature, document it in the apps/next docs folder.
3. If you have a new feature, add a new example in the examples folder.
4. You have a descriptive changeset for each PR:

Bumping the versions of packages you've modified

We use changesets for managing versions and changelogs. To create a new changeset, run in the root folder:

pnpm changeset

You will be prompted to choose what packages need their versions bumped, and what kind of bump (major, minor or patch) is needed. Once you carry out this operation, the bumping will be automatic after the PR is merged.

Publishing (maintainers only)

The Release Github Action is automatically generating and updating a PR called "Release {version}".

This PR will update the package.json and CHANGELOG.md files of each package according to the current changesets in the .changeset folder.

If this PR is merged it will automatically add version tags to the repository and publish the updated packages to NPM.