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.
npm install egg-bin --save-devegg-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";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 --inspectegg-bin is built around several key components:
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;
}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[]>;
}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>;
}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>;
}Convenient alias command that starts the development server with Node.js debugging enabled.
class DebugCommand extends Command {
utils: Utils;
run(): Promise<void>;
}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>;
}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>;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;
}egg-bin automatically detects TypeScript support through multiple methods:
EGG_TYPESCRIPT environment variable ('true' or 'false')pkg.egg.typescript in package.jsontypescript in dependencies or devDependenciestsconfig.json file--tscompiler option providedFor packages with "type": "module" in package.json, egg-bin automatically configures ESM loader support with ts-node/esm.
Configure security reverts through package.json:
{
"egg": {
"revert": ["CVE-2023-46809"]
}
}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;
}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.