DOCSEARCHbyAlgolia
Submit Docs

Nadle API Reference

website·Indexed 30 days ago

https://nadle.dev

Documentation for Nadle, featuring a task-based system with support for defining tasks via defineTask and plugins via definePlugin. The API includes built-in task types such as ExecTask, CopyTask, DeleteTask, DownloadTask, and ZipTask, as well as configuration options for Node, Npx, and Pnpm execution.

Tokens
24.9K
Snippets
171
Records
217
Agent score
49%

What's inside Nadle

  2. Overview of Nadle task runner

    Nadle is a modern, type-safe, Gradle-inspired task runner for Node.js built with TypeScript. It allows developers to define and orchestrate project workflows using a declarative nadle.config.ts file. Key capabilities include:

    • Type Safety: Full type inference and compile-time validation for tasks.
    • Parallel Execution: Automatic execution of independent tasks using worker threads.
    • Incremental Builds: Built-in caching based on declared inputs and outputs to skip unchanged tasks.
    • Task Management: Support for task grouping, descriptions, and explicit dependency declarations.
    • CLI UX: Interactive footer for real-time progress tracking and abbreviation matching (e.g., running b for build).

  3. Manage tasks in a monorepo

    Nadle automatically detects monorepos managed by pnpm (pnpm-workspace.yaml), npm, or yarn (package.json workspaces). It treats each workspace as a distinct unit with its own configuration. Tasks can be referenced by workspace ID, relative path, or alias using the <workspace>:<task> format. If a task is not found in the current workspace, Nadle falls back to the root workspace.
    # Run a task in all workspaces
nadle build

# Run a task in a specific workspace
nadle workspace-a:deploy

# Exclude a task in a specific workspace
nadle build --exclude workspace-b:build

# Run multiple tasks in parallel
nadle eslint prettier spell-check --parallel

  4. Core features and design goals of Nadle

    Nadle is a type-safe, Gradle-inspired task runner for Node.js designed to replace string-based scripts with a programmable and declarative approach. Its core design principles include:

    • Type Safety: Prevents misspelled task names and logic errors common in stringified scripts.
    • Declarative & Programmable: Allows clear declaration of task dependencies and the use of real code to express complex workflows.
    • Ecosystem Native: Built with ESM and respects standard Node.js conventions for easy integration with frontend and backend stacks.
    • Scalability: Supports a progression from a single task to a full monorepo without requiring a change in tooling.
    • Extensibility: Supports plugins, custom tasks, and shared utilities.

  5. Declare file and directory output patterns for caching

    The Outputs namespace provides utilities for declaring file and directory output patterns used for caching. These utilities are aliases of Inputs.files and Inputs.dirs and include the files and dirs variables.

  6. Extend Nadle functionality using plugins

    Plugins are distributable units of behavior that must be explicitly opted into. A plugin can contribute:

    1. Task types: Ready-made tasks (e.g., deploy).
    2. Lifecycle hooks: Callbacks that execute around the build or individual tasks.
    3. Custom reporters: Alternative output formats selectable via the --reporter <name> CLI flag.

  7. Use TaskExecutionError to handle task failures

    The TaskExecutionError class is thrown when a task fails during its execution. It extends NadleError and provides additional context about which task caused the failure via the task property.
    // Constructor signature
new TaskExecutionError(message: string, options?: TaskExecutionErrorOptions): TaskExecutionError

  8. Use TaskHookContext in task-level hooks

    The TaskHookContext<Options> interface is passed to beforeTask and afterTask hooks. It provides metadata about the task execution, logging capabilities, and plugin configuration.
    interface TaskHookContext<Options> {
  readonly task: RegisteredTask;
  readonly logger: Logger;
  readonly pluginOptions: Options;
  readonly threadId?: number; // Present in beforeTask (worker thread id)
  readonly result?: 'up-to-date' | 'from-cache' | 'skipped' | 'failed' | 'canceled' | 'done'; // Present only in afterTask
  readonly error?: unknown; // Present only in afterTask when result is 'failed'
}

  9. Use Task and Workspace Name Autocorrect

    Nadle automatically suggests and corrects task and workspace names if they are mistyped or provided as partial names, allowing the command to resolve to the intended target.
    # Mistyped 'backend:build' as 'backe:biuld'
nadle backe:biuld

# Nadle will resolve to 'backend:build'

  10. Use the Inputs namespace for cache input declarations

    The Inputs namespace provides utility functions for declaring file and directory input patterns used for caching. Available functions include dirs() for directory patterns and files() for file patterns.

  11. Install Nadle shell completion

    Nadle supports shell completion for bash, zsh, and fish. The completion command generates the necessary script. Append this output to your shell profile to enable TAB completion for option flags and live task names (including task descriptions in supported shells).
    nadle completion >> ~/.zshrc   # or ~/.bashrc, or fish config

  12. Configure Nadle LSP for Helix

    To use the Nadle LSP in Helix, install the language server globally via npm and update your languages.toml to include the nadle server for TypeScript files.
    npm install -g @nadle/language-server
    [language-server.nadle]
command = "nadle-language-server"

[[language]]
name = "typescript"
language-servers = ["typescript-language-server", "nadle"]