LlamaIndex Tutorial (TypeScript): chunking large documents for beginners

This tutorial shows you how to split large documents into smaller chunks with LlamaIndex in TypeScript, then inspect those chunks before sending them into an index or LLM pipeline. You need this when your source files are too large for a model context window, or when you want more precise retrieval from long PDFs, docs, or transcripts.

What You'll Need

• •Node.js 18+ installed
• •A TypeScript project initialized
• •llamaindex installed
• •An OpenAI API key set in your environment
• •A large text file to test with, for example ./data/handbook.txt
• •Basic familiarity with async/await and ES modules

Install the package:

npm install llamaindex
npm install -D typescript tsx @types/node

Set your API key:

export OPENAI_API_KEY="your-key-here"

Step-by-Step

1. •Start by loading a document from disk. LlamaIndex works with Document objects, so the first job is to read your file and wrap it in the right shape.

import { Document } from "llamaindex";
import { readFileSync } from "node:fs";

const text = readFileSync("./data/handbook.txt", "utf-8");

const document = new Document({
  text,
  metadata: {
    source: "handbook.txt",
  },
});

console.log("Loaded characters:", document.text.length);

2. •Next, create a chunking pipeline using SentenceSplitter. This is the standard way to break long text into smaller nodes while keeping sentence boundaries intact.

import { SentenceSplitter } from "llamaindex";

const splitter = new SentenceSplitter({
  chunkSize: 512,
  chunkOverlap: 64,
});

const chunks = splitter.splitText(document.text);

console.log("Chunk count:", chunks.length);
console.log("First chunk preview:");
console.log(chunks[0].slice(0, 300));

3. •If you want metadata preserved per chunk, convert the document into nodes instead of only splitting raw text. This is the better pattern once you move beyond inspection and into indexing.

import { SentenceSplitter } from "llamaindex";
import { Document } from "llamaindex";

const splitter = new SentenceSplitter({
  chunkSize: 512,
  chunkOverlap: 64,
});

const document = new Document({
  text: "Your large document content goes here.",
  metadata: {
    source: "handbook.txt",
    department: "ops",
  },
});

const nodes = splitter.getNodesFromDocuments([document]);

for (const node of nodes.slice(0, 3)) {
  console.log("Node ID:", node.id_);
  console.log("Text:", node.text.slice(0, 120));
  console.log("Metadata:", node.metadata);
}

4. •Now put those chunks into a vector index. This is where chunking becomes useful in practice, because retrieval will operate over smaller passages instead of one giant blob.

import { Document, VectorStoreIndex } from "llamaindex";
import { readFileSync } from "node:fs";

async function main() {
  const text = readFileSync("./data/handbook.txt", "utf-8");

  const docs = [
    new Document({
      text,
      metadata: { source: "handbook.txt" },
    }),
  ];

  const index = await VectorStoreIndex.fromDocuments(docs);
  const queryEngine = index.asQueryEngine();

  const response = await queryEngine.query({
    query: "What does the handbook say about leave requests?",
  });

  console.log(response.toString());
}

main();

5. •Finally, tune chunk size based on the document type. Policies and contracts usually work better with smaller chunks; technical manuals can tolerate larger ones if sections stay coherent.

import { SentenceSplitter } from "llamaindex";

const configs = [
  { name: "small", chunkSize: 256, chunkOverlap: 32 },
  { name: "medium", chunkSize: 512, chunkOverlap: 64 },
  { name: "large", chunkSize: 1024, chunkOverlap: 128 },
];

const sampleText =
  "Section one. This is a long paragraph with multiple sentences. It should be split carefully.";

for (const config of configs) {
  const splitter = new SentenceSplitter(config);
  const parts = splitter.splitText(sampleText);

  console.log(`${config.name}: ${parts.length} chunks`);
}

Testing It

Run each script with npx tsx filename.ts and confirm that the output shows multiple chunks rather than one large string. If you use getNodesFromDocuments, check that each node carries the metadata you attached to the original document.

For retrieval testing, ask a question that only appears in one section of your document and verify that the answer comes from the relevant chunk. If results are too broad, lower chunkSize; if they feel fragmented, increase it slightly and rerun.

A good sanity check is to print chunk previews and make sure sentence boundaries look natural. If chunks start or end mid-sentence too often, your overlap or splitter settings need adjustment.

Next Steps

• •Add a persistent vector store like Pinecone or PostgreSQL so your chunks survive process restarts.
• •Learn how to use hierarchical parsing for PDFs and markdown-heavy documents.
• •Add evaluation scripts to compare retrieval quality across different chunkSize settings.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.