nci.config.json, end to end
Every flag the CLI accepts has a config-file equivalent. Build a config interactively below — the JSON on the right updates live and stays valid against the engine’s schema.
Schema at a glance
| Key | Type | Role |
|---|---|---|
database | string (path) | SQLite file path |
project_root | string (path) | Consumer repo root (package.json, node_modules) |
format | plain | json | jsonl | Default stdout shape for query commands |
banner | auto | on | off | Startup banner on stderr |
progress | auto | on | off | Progress lines on stderr |
max_hops | integer | Re-export follow depth (0, 10 default, -1 unlimited) |
packages | object | include / exclude package-name globs |
package_scope | array or "all_installed" | Which manifest sections gate indexing |
dependency_stub_packages | string[] | Crawl-skip list → npm::… stub edges |
workspaces | string[] | Monorepo workspace directory globs |
index_root_workspace | boolean | Scan <project_root>/node_modules (default true) |
Build it
{
"project_root": ".",
"package_scope": [
"dependencies"
],
"banner": "auto",
"progress": "auto",
"max_hops": 10
}Field deep-dives
database
Path to the SQLite index file. Relative paths resolve against the directory that contains nci.config.json. When omitted, NCI uses the OS cache layout (overridable with NCI_CACHE_DIR — see Environment variables).
CLI equivalent: --database <PATH>.
project_root
The directory whose package.json and node_modules are scanned. Relative paths resolve against the file containing the config — not against cwd. If you run nci index from a workspace, the file’s project_root still wins unless --project-root is passed.
format
Default output encoding for nci query (and related commands): plain, json, or jsonl. Does not change how indexing works — only how results are printed. Per-command --format overrides.
banner
Controls the startup banner on stderr: auto (TTY only), on, or off.
progress
Controls index/query progress lines on stderr: auto (TTY only), on, or off. Plain nci index per-package lines show end-to-end time per package (in 1m20s from work start through SQLite insert). Add CLI --index-timing-detail for a crawl / queue / save split; the final summary line includes total wall time for the run.
package_scope
Either an array of sections or the sentinel.
{ "package_scope": ["dependencies"] }
Indexes packages listed in the consumer manifest’s dependencies. Add "dev_dependencies" to include build tools. Omit = ["dependencies"] only.
{ "package_scope": "all_installed" }
Disables the manifest gate. Every installed package is indexed regardless of how it got there. Use sparingly — large transitive trees are not free.
CLI: --package-scope dependencies,dev-dependencies or --package-scope all-installed.
max_hops
The depth of re-export resolution.
| Value | Behaviour |
|---|---|
0 | Index entry-file declarations only |
1 | Follow one level (entry → re-exported file) |
10 | Default — covers practically every real lib |
-1 | Unlimited — only useful for diagnostics |
packages
Optional package-name globs applied after package_scope narrows the install set.
{ "packages": { "include": ["@my-org/*"], "exclude": ["eslint*", "@types/*"] } }
include: keep only names matching at least one glob (if non-empty).exclude: drop names matching any pattern.
CLI --package globs are unioned with packages.include for one-off runs. See Monorepo guide for incremental indexing patterns.
workspaces
Glob list, relative to project_root. Each entry contributes its own node_modules install root.
{ "workspaces": ["apps/*", "packages/*"] }
Patterns ending in /* expand to immediate child directories; a path without /* must exist as a single directory.
dependency_stub_packages
Package names (bare or scoped) whose .d.ts trees are not crawled. Consumer imports become npm::<specifier>::<member> stub edges instead. Merged with CLI -s / --dependency-stub-package (union, not replace).
index_root_workspace
When true or omitted, <project_root>/node_modules is scanned. When false, the root install root is skipped — you must list at least one workspaces entry so another …/node_modules remains.
CLI: --skip-root-workspace forces off; --include-root-workspace forces on for one run (overrides false in the file).
Verify
would index 78 packages would write 13.4 MiB to nci.sqlite
If the package count surprises you, narrow package_scope, add packages.exclude globs, or set index_root_workspace / --skip-root-workspace for monorepos that hoist only in workspaces.