egg

# Eggjs Framework - GitHub Copilot Development Instructions

**Always reference these instructions first and fallback to search or additional context gathering only when you encounter unexpected information that does not match the information provided here.**

## Overview

Eggjs is a progressive Node.js framework for building enterprise-class server-side applications. Built on top of Koa.js, it provides a plugin system, conventions over configuration, and enterprise-grade features like clustering, logging, and security.

This is a **utoo monorepo** with multiple packages using utoo workspaces and catalog mode for centralized dependency management.

## Prerequisites and Environment Setup

- **Node.js >= 22.18.0 required** - This is a hard requirement
- Enable utoo first: `npm install --global utoo@latest`
- **NEVER CANCEL** any build or test commands - they can take several minutes to complete

## Bootstrap and Build Process

**Run these commands after a fresh clone:**

```bash
# 1. Enable utoo (required first)
npm install --global utoo@latest

# 2. Install all dependencies - takes ~63 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
ut install

# 3. Run lint to check code quality across all packages - takes ~2 seconds
ut run lint

# 4. Build all packages when validating build output - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
ut run build
```

Run unit tests from a clean source tree, not immediately after `ut run build`.
The main CI test job installs dependencies with `ut install` and
runs tests with `ut run ci`; it does not run `build` before tests.

## Monorepo Structure

### Key Packages (all in `packages/` directory)

- **`packages/egg/`** - Main Eggjs framework (TypeScript, uses tsdown for builds)
- **`packages/core/`** - Core plugin framework
- **`packages/utils/`** - Utility functions
- **`packages/mock/`** - Testing utilities
- **`packages/cluster/`** - Cluster management
- **`packages/koa/`** - Koa web framework
- **`packages/supertest/`** - HTTP testing utilities
- **`packages/extend2/`** - Object extension utility

### Supporting Directories

- **`examples/`** - Two example apps: `helloworld-commonjs` and `helloworld-typescript` (currently have runtime issues)
- **`site/`** - Documentation website built with VitePress

## Essential Commands and Timing

### Build Commands

- `ut run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
- `ut run clean-dist` - Clean all dist directories

### Testing Commands

- `ut run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
- `ut run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
- `ut run ci` - **Run tests with coverage (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**

### Linting Commands

- `ut run lint` - Run oxlint across all packages (~2 seconds)

### Documentation Commands

- `ut run site:dev` - Start documentation dev server (defaults to VitePress port 5173)
- `ut run site:build` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**

### Example Applications (Currently Not Working)

- `ut run example:dev:commonjs` - Start CommonJS example (has runtime issues)
- `ut run example:dev:typescript` - Start TypeScript example (has runtime issues)

## Package-Specific Commands

Run commands for specific packages using `ut --filter=<package>`:

```bash
# Examples
ut --filter=egg run test
ut --filter=@eggjs/core run build
ut --filter=site run dev
```

## Development Workflow

### 1. Making Changes

- Work from the source tree first. Build when you need to validate package output, but do not run build immediately before unit tests.
- Work primarily in `packages/egg/src/` for core framework features
- Use TypeScript throughout - all packages are TypeScript-based
- Follow the existing directory conventions in `packages/egg/src/`:
  - `lib/` - Core classes (Application, Agent, EggApplicationCore)
  - `app/extend/` - Framework extensions (context, helper, request, response)
  - `config/` - Default configurations and plugins
  - `lib/core/` - Core components (httpclient, logger, messenger)
  - `lib/loader/` - Application loaders

### 2. Validation Steps

**Always perform these validation steps after making changes:**

```bash
# 1. Run lint to check code quality across all packages
ut run lint

# 2. Run tests from a clean tree (some failures are expected in fresh environment)
ut run test

# 3. Build all packages when build output or packaging behavior is relevant
ut run build

# 4. Test documentation site when docs changed
ut run site:dev
```

### 3. Testing Strategy

- **All packages use Vitest for testing** - this is the standard test runner
- Test files follow pattern: `test/**/*.test.ts`
- Use `import { describe, it } from 'vitest'` for test functions
- Use Node.js built-in `assert` module for assertions
- Create test fixtures in `packages/egg/test/fixtures/apps/` for scenario testing

## Key Framework Concepts

### Architecture

- **EggApplicationCore** - Base application class with core functionality
- **Application** - Main app class for worker processes
- **Agent** - Agent process class for background tasks
- **Context** - Extended Koa context with Egg-specific features
- **BaseContextClass** - Base for controllers, services, subscriptions

### Loading Convention (Automatic Discovery Order)

1. Plugin system
2. Configurations
3. Application/Request/Response/Context extensions
4. Custom loaders
5. Services
6. Middlewares
7. Controllers
8. Router

### Cluster vs Single Mode

- **Cluster Mode** (default) - Multi-process with master, agent, and worker processes
- **Single Mode** - Single process for development/testing

## Working with TypeScript

- All packages use strict TypeScript mode
- Uses tsdown for unbundled ESM builds (preserves file structure)
- Each package has `tsdown.config.ts` for build configuration
- **All sub-project tsconfig.json files MUST extend from root:** `"extends": "../../tsconfig.json"`
- Root tsconfig.json includes all packages in `references` array

## utoo Workspace & Catalog Dependencies

- Dependencies defined in `.utoo.toml` catalog section
- Reference catalog entries: `"package-name": "catalog:"`
- Internal workspace dependencies: `"package-name": "workspace:*"`
- This ensures consistent versions across all packages

## Common Issues and Troubleshooting

### Test Failures

- Some tests may fail in fresh environments - this is normal
- Focus on fixing only failures related to your changes
- Examples may have runtime issues - don't use them for validation
- If tegg tests fail with `duplicate proto` after a local build, remove stale
  `dist/` directories outside fixtures and re-run tests. Built `dist/*.js`
  files can be scanned alongside `src/*.ts`, loading the same decorated class
  twice.

### Build Issues

- Run `ut run build` when validating build output, package exports, or changes
  that affect generated artifacts.
- TypeScript compilation errors will show clearly
- Build warnings are generally acceptable

### ESM/CommonJS Issues

- Framework supports both ESM and CommonJS
- Main package exports both formats
- If you see "ERR_UNKNOWN_FILE_EXTENSION" errors, ensure packages are built first

## File Locations Reference

### Key Configuration Files

- `package.json` / `.utoo.toml` - Workspace patterns and catalog configuration
- `package.json` - Root monorepo scripts and devDependencies
- `packages/egg/package.json` - Main framework package configuration
- `packages/egg/tsdown.config.ts` - Build configuration
- `packages/egg/src/config/plugin.ts` - Built-in plugin configurations
- `packages/egg/src/config/config.default.ts` - Default framework configuration

### Important Source Files

- `packages/egg/src/lib/application.ts` - Main Application class
- `packages/egg/src/lib/agent.ts` - Agent process manager
- `packages/egg/src/lib/egg.ts` - Core EggApplicationCore
- `packages/egg/src/lib/start.ts` - Application startup logic
- `packages/egg/src/lib/loader/` - Convention-based loaders

### Build Outputs

- `packages/*/dist/` - Built JavaScript and TypeScript definitions
- `site/dist/` - Built documentation site

## Validation Scenarios

After making changes, always verify:

1. **Linting Passes**: `ut run lint` shows no new errors
2. **Tests Run From Clean Sources**: `ut run test` executes without stale build artifacts interfering
3. **Documentation Loads**: `ut run site:dev` starts successfully and the printed VitePress URL responds
4. **Build Success When Relevant**: `ut run build` completes without errors

**Remember**: This is a complex enterprise framework. Validate incrementally, keep unit tests isolated from stale build artifacts, and focus on the core packages (`egg`, `core`, `utils`) for most development work.

## Commit Message Format

**CRITICAL: All commits MUST follow the [Angular Commit Message Format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) as specified in CONTRIBUTING.md.**

### Required Format Structure

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

### Mandatory Types

- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation-only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
- **deps**: Updates about dependencies

### Scope Guidelines

- **Package-specific changes**: Use package names like `core`, `mock`, `cluster`, `utils`, `tsconfig`, `extend2`
- **Cross-package changes**: Use feature areas like `loader`, `plugin`, `config`, `build`
- **Component-specific**: Use component names like `application`, `agent`, `context`

### Subject Rules

- Use imperative, present tense: "change" not "changed" nor "changes"
- Don't capitalize first letter
- No period (.) at the end
- Be succinct and descriptive

### Examples

```
feat(tsconfig): integrate package into monorepo with vitest

Merge @eggjs/tsconfig repository into packages/tsconfig/ and refactor
to use vitest testing framework instead of Node.js test runner.

- Update all consuming packages to use workspace:* dependencies
- Add vitest configuration and convert test assertions
- Remove external catalog dependency in favor of workspace package

Closes #123
```

```
fix(core): resolve loader initialization race condition

The loader was attempting to initialize plugins before configurations
were fully loaded, causing intermittent startup failures.

Fixes #456
```

```
chore: update dependencies to latest versions

Update catalog dependencies and rebuild packages to ensure
compatibility with latest versions.
```

**NEVER commit without following this format - it breaks the project's automated changelog and release process.**

More agent context in eggjs/egg

2 other files this repository gives its agents.