or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdconfiguration.mdindex.mdprogrammatic-api.md
tile.json

index.mddocs/

@antfu/ni

@antfu/ni is a universal package manager interface that automatically detects the appropriate package manager (npm, yarn, pnpm, or bun) based on lock files in your project and executes the corresponding commands. It provides both CLI tools and a programmatic API for seamless package manager operations across different project types.

Package Information

  • Package Name: @antfu/ni
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -g @antfu/ni

Core Imports

import { 
  detect, 
  getConfig, 
  getDefaultAgent, 
  parseNi, 
  parseNr, 
  runCli, 
  getCommand,
  fetchNpmPackages,
  getPackageJSON,
  getEnvironmentOptions,
  formatPackageWithUrl 
} from "@antfu/ni";

For CommonJS:

const { 
  detect, 
  getConfig, 
  getDefaultAgent, 
  parseNi, 
  parseNr, 
  runCli, 
  getCommand,
  fetchNpmPackages,
  getPackageJSON,
  getEnvironmentOptions,
  formatPackageWithUrl 
} = require("@antfu/ni");

Basic Usage

CLI Commands

The package provides seven CLI commands that automatically detect and use the correct package manager:

# Install dependencies
ni

# Install specific packages  
ni vite react

# Run scripts
nr dev

# Execute packages
nlx create-react-app my-app

# Upgrade dependencies
nup

# Uninstall packages
nun webpack

# Clean install
nci

# Direct package manager access
na run build

Programmatic Usage

import { detect, parseNi, runCli } from "@antfu/ni";

// Detect package manager from current directory
const agent = await detect({ cwd: process.cwd() });
console.log(agent); // 'npm' | 'yarn' | 'pnpm' | 'bun'

// Parse install command for detected agent
const command = parseNi(agent, ['react', 'vue']);
console.log(command); // { command: 'npm', args: ['install', 'react', 'vue'] }

// Run CLI command programmatically
await runCli(parseNi, { 
  args: ['react'], 
  programmatic: true 
});

Architecture

@antfu/ni is built around several key components:

  • Package Manager Detection: Automatic detection via lock files and packageManager field
  • Command Parsing: Transforms ni commands into package manager-specific commands
  • CLI Runners: Execute commands with proper agent detection and error handling
  • Configuration System: User preferences via .nirc file and environment variables
  • Interactive Mode: Prompts for package selection, script running, and dependency management

Capabilities

CLI Commands

Seven command-line tools that provide a unified interface across all package managers. Each command automatically detects the appropriate package manager and executes the equivalent command.

// Available CLI commands
type CliCommand = 'ni' | 'nr' | 'nlx' | 'nup' | 'nun' | 'nci' | 'na';

CLI Commands

Programmatic API

Core functions for package manager detection, command parsing, and programmatic execution. Perfect for build tools and development scripts that need package manager abstraction.

function detect(options?: DetectOptions): Promise<Agent | undefined>;
function parseNi(agent: Agent, args: string[], ctx?: RunnerContext): ResolvedCommand | undefined;
function runCli(fn: Runner, options?: DetectOptions & { args?: string[] }): Promise<void>;

Programmatic API

Configuration

Configuration management through .nirc files and environment variables, allowing users to set default and global package managers.

interface Config {
  defaultAgent: Agent | 'prompt';
  globalAgent: Agent;
}

function getConfig(): Promise<Config>;
function getDefaultAgent(programmatic?: boolean): Promise<Agent | 'prompt'>;
function getGlobalAgent(): Promise<Agent>;

Configuration

Types

// Package manager types
type Agent = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'yarn@berry' | 'pnpm@6' | 'pnpm@7' | 'pnpm@8' | 'pnpm@9';

// Command types  
type Command = 'install' | 'add' | 'upgrade' | 'remove' | 'global' | 'run' | 'dlx' | 'upgrade-interactive';

// Resolved command structure
interface ResolvedCommand {
  command: string;
  args: string[];
}

// Detection options
interface DetectOptions {
  autoInstall?: boolean;
  programmatic?: boolean;
  cwd?: string;
  detectVolta?: boolean;
}

// Runner context
interface RunnerContext {
  programmatic?: boolean;
  hasLock?: boolean;
  cwd?: string;
}

// Configuration interface
interface Config {
  defaultAgent: Agent | 'prompt';
  globalAgent: Agent;
}

// Environment options
interface EnvironmentOptions {
  autoInstall: boolean;
}

// NPM package metadata
interface NpmPackage {
  name: string;
  description: string;
  version: string;
  keywords: string[];
  date: string;
  links: {
    npm: string;
    homepage: string;
    repository: string;
  };
}