Package Registry Guide

NodeTool packages bundle reusable nodes, assets, and example workflows. The package registry discovers and registers node classes so workflows can reference them at runtime.

Package Anatomy

A package is a standard npm workspace package that exports node classes and a registration function:

package.json – declares the package name, dependencies, and build scripts.
src/nodes/ – node implementations, one file per domain (e.g. list.ts, audio.ts).
src/index.ts – exports all node classes and a register*Nodes() function.
tsconfig.json – extends the workspace base config.
examples/ – optional workflow examples.
assets/ – optional static assets used by nodes.

Example `package.json`

{
  "name": "@nodetool/base-nodes",
  "type": "module",
  "version": "0.1.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
    "test": "vitest run",
    "lint": "tsc --noEmit"
  },
  "dependencies": {
    "@nodetool/node-sdk": "*"
  }
}

Every node package depends on @nodetool/node-sdk, which provides BaseNode, the @prop decorator, and the NodeRegistry type.

Example `tsconfig.json`

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Node Registration

Each package exports a constant array of node classes and a registration function. The pattern used by @nodetool/base-nodes:

import type { NodeClass, NodeRegistry } from "@nodetool/node-sdk";
import { LIST_NODES } from "./nodes/list.js";
import { TEXT_NODES } from "./nodes/text.js";

export const ALL_BASE_NODES: readonly NodeClass[] = [
  ...LIST_NODES,
  ...TEXT_NODES,
  // ... additional node groups
];

export function registerBaseNodes(registry: NodeRegistry): void {
  for (const nodeClass of ALL_BASE_NODES) {
    registry.register(nodeClass);
  }
}

At startup, the runtime creates a NodeRegistry and calls each package’s registration function. Workflows referencing nodetool.list.Length or mypack.math.AddOffset resolve through the registry without manual imports.

Managing Packages via CLI

List Packages

nodetool package list
nodetool package list --available    # fetch registry index

Displays installed packages (local metadata) or remote entries hosted at the package index URL.

Install / Update / Uninstall

nodetool package install <owner>/<repo>
nodetool package update <owner>/<repo>
nodetool package uninstall <owner>/<repo>

These commands install the package, then refresh metadata caches stored under ~/.config/nodetool/packages.

Scan Project

nodetool package scan [--verbose]

Inspects the current repository and generates node metadata.

Generate Documentation

nodetool package docs --output-dir docs/nodes
nodetool package docs --compact     # shorter summaries for LLM prompts

Creates Markdown documentation for all nodes in the project.

Building Packages

Compile TypeScript and prepare the package for use:

npm run build

For type checking without emitting output:

npm run lint

For running tests:

npm run test

Publishing Packages

Implement nodes under src/nodes/ extending BaseNode with @prop decorators.
Export all node classes and a registration function from src/index.ts.
Run npm run build to compile.
Run nodetool package scan to produce node metadata.
Add example workflows in examples/ and assets in assets/ if relevant.
Commit the generated metadata files.
Publish to npm or provide a Git URL.

To add the package to the public index, create an entry in the registry repository so package list --available surfaces it.

Workflow Integration

Installed packages automatically register nodes with the runtime:

Node metadata is merged during startup so workflows referencing package.namespace.Node resolve without manual imports.
Run npm run codegen --workspace=packages/dsl to regenerate typed factory functions from node metadata.

CLI Reference – package subcommands.
Configuration Guide – where package metadata is cached.
Custom Nodes Guide – step-by-step node implementation.
TypeScript DSL Guide – type-safe workflow definitions with @nodetool/dsl.

Edit this page on GitHub