> ## Documentation Index
> Fetch the complete documentation index at: https://narrator.ami.rip/llms.txt
> Use this file to discover all available pages before exploring further.

# @usenarrator/node

> A ready-made narrator for Node and Bun, and the helpers that read a repository's manifests.

```ts theme={null}
import { changedFilesFromGit, createNodeNarrator, findRepoRoot, gitAttributeSkips, listRepoFiles, loadDependencyIndex } from "@usenarrator/node";
```

This package wires `@usenarrator/core`, `@usenarrator/lang-ts` with the native oxc parser, and `@usenarrator/locale-en` together for server-side use. It depends on `oxc-parser`, so it isn't meant for browsers. See [Embedding in your app](/guides/embedding) for the browser setup.

## createNodeNarrator

```ts theme={null}
function createNodeNarrator(options?: {
  plugins?: (TsPlugin | TsPlugin[])[];
  locale?: Locale;
  dependencies?: false | DependencyIndex;
}): Narrator;
```

<ParamField path="plugins" type="(TsPlugin | TsPlugin[])[]">
  Library and codebase plugins, as for `typescript()`.
</ParamField>

<ParamField path="locale" type="Locale">
  The output language. Defaults to English.
</ParamField>

<ParamField path="dependencies" type="false | DependencyIndex">
  Defaults to `loadDependencyIndex({ root: findRepoRoot(process.cwd()) })`, the manifests of the git checkout around the working directory. Pass your own index for another repository, or `false` to rely on imports alone.
</ParamField>

## changedFilesFromGit

```ts theme={null}
function changedFilesFromGit(options: {
  root: string;
  range: string;
  includeGenerated?: boolean;
  accepts?: (path: string) => boolean;
}): ChangedFile[];
```

The files changed in a git range, with both sides' sources, ready for `narrator.diffFiles` or `narrator.diff`. This is what `narrator diff` uses.

<ParamField path="range" type="string" required>
  `base..head` compares two revisions, `base...head` compares `head` with its merge base, and `base` alone compares a revision with the working tree. An unknown revision throws an error that names it.
</ParamField>

<ParamField path="includeGenerated" type="boolean">
  By default, files that `.gitattributes` marks `linguist-generated` or `linguist-vendored`, and files whose path shows they are build output, dependencies or lockfiles, come back with `skipped` set and empty sources, so they are never read. Minified content is caught later by the narrator. Pass `true` to read everything.
</ParamField>

<ParamField path="accepts" type="(path: string) => boolean">
  Drops other paths before anything is read, for example `narrator.canNarrate`.
</ParamField>

All sources are read through one `git cat-file --batch` process, so large ranges stay fast.

```ts theme={null}
import { renderDiffText } from "@usenarrator/core";
import { changedFilesFromGit, createNodeNarrator, findRepoRoot } from "@usenarrator/node";

const narrator = createNodeNarrator();
const root = findRepoRoot(process.cwd());
const files = changedFilesFromGit({ root, range: "main...HEAD", accepts: narrator.canNarrate });
console.log(renderDiffText({ files: narrator.diffFiles(files) }));
```

## gitAttributeSkips

```ts theme={null}
function gitAttributeSkips(options: { root: string; paths: string[] }): Map<string, SkipReason>;
```

The paths that `.gitattributes` marks `linguist-generated` (reason `generated`) or `linguist-vendored` (reason `vendored`). Paths are relative to `root`. Outside git, the map is empty.

## loadDependencyIndex

```ts theme={null}
function loadDependencyIndex(options: { root: string; readers?: ManifestReader[] }): DependencyIndex;
```

A [dependency index](/concepts/dependency-detection) over every manifest in the repository at `root`. Files are listed with `listRepoFiles`, and manifests are read the first time the index is used. File paths passed to `forFile` may be absolute or relative to `root`.

## findRepoRoot

```ts theme={null}
function findRepoRoot(dir: string, readers?: ManifestReader[]): string;
```

The nearest enclosing directory with a `.git` folder. Outside git, the outermost ancestor that holds a manifest, or `dir` itself.

## listRepoFiles

```ts theme={null}
function listRepoFiles(root: string): string[];
```

Every file in the repository, relative to `root`. It uses `git ls-files`, which respects `.gitignore` and includes untracked files. Outside git it falls back to a directory walk four levels deep that skips `node_modules`, `dist`, hidden folders and similar.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.