or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

base-command.mdcoverage-testing.mddebug-command.mddevelopment-server.mdindex.mdtest-runner.md
tile.json

tessl/npm-egg-bin

Developer tool for Egg.js framework providing development server, testing, coverage, and debugging capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/egg-bin@6.13.x

To install, run

npx @tessl/cli install tessl/npm-egg-bin@6.13.0

index.mddocs/

egg-bin

egg-bin is a comprehensive developer tool for the Egg.js framework, built on top of Artus CLI. It provides essential development commands including dev server startup with hot reload and clustering support, testing with Mocha integration and TypeScript compatibility, code coverage reporting using c8, and advanced debugging capabilities with VSCode integration.

Package Information

  • Package Name: egg-bin
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install egg-bin --save-dev

Core Imports

egg-bin is a CLI tool, not a library. It's used as a command-line executable:

# Install as dev dependency
npm install egg-bin --save-dev

# Use via npx
npx egg-bin dev

# Or via package.json scripts
npm run dev  # where "dev": "egg-bin dev"

For programmatic access to command classes (advanced usage):

import { 
  DevCommand, 
  TestCommand, 
  CovCommand, 
  DebugCommand, 
  BaseCommand,
  addNodeOptionsToEnv,
  readPackageJSON,
  hasTsConfig
} from "egg-bin";

Basic Usage

Add egg-bin to your package.json scripts:

{
  "scripts": {
    "dev": "egg-bin dev",
    "test-local": "egg-bin test",
    "test": "npm run lint -- --fix && npm run test-local",
    "cov": "egg-bin cov",
    "lint": "eslint .",
    "ci": "npm run lint && npm run cov"
  }
}

Example development server usage:

# Start development server
egg-bin dev

# Start with specific port and workers
egg-bin dev --port 8000 --workers 2

# Enable TypeScript support with debugging
egg-bin dev --typescript --inspect

Architecture

egg-bin is built around several key components:

  • CLI Framework: Built on @artus-cli/artus-cli for robust command-line interface
  • Command System: Modular command classes extending a common BaseCommand
  • Middleware System: Global options and inspection middleware for cross-cutting concerns
  • Process Management: Graceful process forking and signal handling for development workflows
  • TypeScript Integration: Automatic TypeScript detection and compilation support
  • Testing Integration: Mocha-based testing with coverage reporting via c8

Capabilities

Development Server

Start a development server with hot reload, clustering support, and automatic port detection. Ideal for rapid development with automatic restarts and debugging integration.

class DevCommand extends BaseCommand {
  port: number;
  workers: number;
  framework: string;
  sticky: boolean;
  
  run(): Promise<void>;
  protected formatEggStartOptions(): Promise<EggStartOptions>;
}

interface EggStartOptions {
  baseDir: string;
  workers: number;
  port: number;
  framework: string;
  typescript: boolean;
  tscompiler: string;
  sticky: boolean;
}

Development Server

Test Runner

Execute test suites using Mocha with support for TypeScript, parallel execution, changed file detection, and comprehensive reporting options.

class TestCommand extends BaseCommand {
  files: string[];
  timeout: number | boolean;
  grep: string[];
  changed: boolean;
  parallel: boolean;
  jobs: number;
  autoAgent: boolean;
  mochawesome: boolean;
  bail: boolean;
  
  run(): Promise<void>;
  protected formatMochaArgs(): Promise<string[] | undefined>;
  protected getChangedTestFiles(dir: string, ext: string): Promise<string[]>;
}

Test Runner

Coverage Testing

Run tests with code coverage analysis using c8, including customizable exclusion patterns and multiple output formats.

class CovCommand extends TestCommand {
  prerequire: boolean;
  x: string[];
  c8: string;
  
  get defaultExcludes(): string[];
  protected forkNode(modulePath: string, args: string[]): Promise<void>;
}

Coverage Testing

Base Command Framework

Abstract base class providing common functionality for all commands including process forking, requirement handling, and graceful shutdown management.

abstract class BaseCommand extends Command {
  dryRun: boolean;
  require: string[];
  ctx: CommandContext;
  utils: Utils;
  
  protected get base(): string;
  
  run(): Promise<void>;
  protected formatRequires(): Promise<string[]>;
  protected forkNode(modulePath: string, args: string[], options?: ForkOptions): Promise<void>;
}

Base Command Framework

Debug Command

Convenient alias command that starts the development server with Node.js debugging enabled.

class DebugCommand extends Command {
  utils: Utils;
  run(): Promise<void>;
}

Debug Command

Middleware System

egg-bin uses Artus CLI middleware for cross-cutting concerns:

/**
 * Global Options Middleware
 * Handles TypeScript detection, base directory resolution, and environment setup
 */
class GlobalOptions implements ApplicationLifecycle {
  configDidLoad(): Promise<void>;
}

/**
 * Inspect Middleware  
 * Handles Node.js debugging options and timeout configuration
 */
class InspectMiddleware implements ApplicationLifecycle {
  configDidLoad(): Promise<void>;
}

Utility Functions

The following utility functions are exported and can be used when extending egg-bin:

/**
 * Utility functions for Node.js option management and configuration
 * Located in src/utils.ts
 */
function addNodeOptionsToEnv(options: string, env: Record<string, any>): void;
function readPackageJSON(baseDir: string): Promise<object>;
function hasTsConfig(baseDir: string): Promise<boolean>;

Global Options

All commands support these global options through middleware:

interface GlobalOptions {
  /** Application base directory, default process.cwd() */
  base?: string;
  baseDir?: string;
  
  /** Enable TypeScript support with auto-detection */
  typescript?: boolean;
  ts?: boolean;
  
  /** TypeScript compiler module (ts-node/register, @swc-node/register, etc.) */
  tscompiler?: string;
  tsc?: string;
  
  /** Generate TypeScript declarations using egg-ts-helper */
  declarations?: boolean;
  dts?: boolean;
  
  /** Additional modules to require before execution */
  require?: string[];
  
  /** Node.js inspector debugging options */
  inspect?: boolean;
  "inspect-brk"?: boolean;
  
  /** Dry run mode - show command without executing */
  "dry-run"?: boolean;
}

TypeScript Auto-Detection

egg-bin automatically detects TypeScript support through multiple methods:

  1. EGG_TYPESCRIPT environment variable ('true' or 'false')
  2. pkg.egg.typescript in package.json
  3. typescript in dependencies or devDependencies
  4. Presence of tsconfig.json file
  5. --tscompiler option provided

ESM Module Support

For packages with "type": "module" in package.json, egg-bin automatically configures ESM loader support with ts-node/esm.

Security Revert Support

Configure security reverts through package.json:

{
  "egg": {
    "revert": ["CVE-2023-46809"]
  }
}

Types

Core TypeScript interfaces and types:

import { ForkOptions } from "child_process";
import { CommandContext, Utils, Command } from "@artus-cli/artus-cli";

interface EggStartOptions {
  baseDir: string;
  workers: number;
  port: number;
  framework: string;
  typescript: boolean;
  tscompiler: string;
  sticky: boolean;
}

interface GlobalOptions {
  base?: string;
  baseDir?: string;
  typescript?: boolean;
  ts?: boolean;
  tscompiler?: string;
  tsc?: string;
  declarations?: boolean;
  dts?: boolean;
  require?: string[];
  inspect?: boolean;
  "inspect-brk"?: boolean;
  "dry-run"?: boolean;
}

Error Handling

egg-bin includes robust error handling:

class ForkError extends Error {
  code: number | null;
  constructor(message: string, code: number | null);
}

Commands that fail will throw ForkError with the appropriate exit code for proper CI/CD integration.