[ { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\n\nopen_collective: eggjs # Replace with a single Open Collective username\n\n\n# github: [ fengmk2, popomore, atian25, dead_horse ] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]\n# patreon: # Replace with a single Patreon username\n# ko_fi: # Replace with a single Ko-fi username\n# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\n# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\n# liberapay: # Replace with a single Liberapay username\n# issuehunt: # Replace with a single IssueHunt username\n# otechie: # Replace with a single Otechie username\n# custom: # Replace with a single custom sponsorship URL\n" }, { "path": ".github/ISSUE_TEMPLATE/bug-report-cn.yml", "content": "name: 🐛 Egg Bug 反馈\ndescription: 如发现 Egg 框架中的 Bug，请及时在此汇报。\nlabels: [bug]\nbody:\n - type: textarea\n attributes:\n label: |\n 在此输入你需要反馈的 Bug 具体信息（Bug in Detail）：\n placeholder: |\n 1. 我做了什么。\n\n 2. 我的预期值。\n\n 3. 我实际得到的结果。\n\n 4. 可以的话，请提供一些截图、视频作为附件以复现症状。\n validations:\n required: true\n - type: textarea\n attributes:\n label: 可复现问题的仓库地址（Reproduction Repo）\n description: |\n 1. 请使用 `npm init egg --type=simple bug` 创建最小可复现问题的代码。\n\n 2. 在 GitHub 中上传该代码项目，并在此处粘贴地址。你也可以直接将你的仓库压缩为 zip 文件直接以附件形式提交。\n placeholder: |\n https://github.com/YOUR_REPOSITORY_URL\n validations:\n required: true\n - type: input\n attributes:\n label: Node 版本号：\n description: |\n 你的当前复现问题的 Node 版本号：\n placeholder: |\n 使用 “node -v” 命令，在控制台得到版本号（例如：v8.5.0）。\n validations:\n required: true\n - type: input\n attributes:\n label: Eggjs 版本号：\n description: |\n 你的当前复现问题 Eggjs 版本号：\n placeholder: |\n 请直接在“package.json”中查阅（例如：3.1.0）。\n validations:\n required: true\n - type: input\n attributes:\n label: '相关插件名称与版本号（PlugIn and Name）：'\n description: |\n 插件名称以及版本号：\n placeholder: |\n 请直接在“package.json”中查阅（例如：egg-mysql，3.1.1）。\n validations:\n required: true\n - type: input\n attributes:\n label: '操作平台与版本号（Platform and Version）：'\n description: |\n 你的操作平台与版本号：\n placeholder: |\n Windows 10 专业版（21H2）\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/bug-report.yml", "content": "name: 🐛 Bug Report For Eggjs\ndescription: Report an issue if something isn't working as expected 🤔.\nlabels: [bug]\nbody:\n - type: textarea\n attributes:\n label: |\n Your detail info about the Bug:\n placeholder: |\n 1. What I did.\n\n 2. What I expected to happen.\n\n 3. What I actually got.\n\n 4. If possible, images/videos as attachments are welcomed to show the bug.\n validations:\n required: true\n - type: textarea\n attributes:\n label: Reproduction Repo\n description: |\n 1. Please use `npm init egg --type=simple bug` to create your smallest repo.\n\n 2. Submit it in the GitHub and paste your URL here. You can also attach your zip file directly.\n placeholder: |\n https://github.com/YOUR_REPOSITORY_URL or your zip file\n validations:\n required: true\n - type: input\n attributes:\n label: Node Version\n description: |\n What's your Node's version?\n placeholder: |\n Use \"node -v\" in your console to get it (e.g: v8.5.0).\n validations:\n required: true\n - type: input\n attributes:\n label: Eggjs Version\n description: |\n What's your Eggjs version?\n placeholder: |\n See it directly in your \"package.json\" file (e.g: 3.1.0)\n validations:\n required: true\n - type: input\n attributes:\n label: Plugin Name and its version\n description: |\n What's your plugin's name and version?\n placeholder: |\n See them directly in your \"package.json\" file (e.g: egg-mysql, 3.1.1)\n validations:\n required: true\n - type: input\n attributes:\n label: Platform and its version\n description: |\n What's your platform and its version?\n placeholder: |\n Windows 10 Professional(21H2)\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/feature-request-cn.yml", "content": "name: 💡 我有一个新点子\ndescription: 我对 Eggjs 框架有一个新的想法（或许我想来实现他）……\nlabels: [feature request]\nbody:\n - type: markdown\n attributes:\n value: |\n 对于 Egg.js 框架，你有一个新的想法？\n 不过在提交你的新点子之前，麻烦请检阅一下是否之前的帖子中有类似重复的内容。\n - type: textarea\n attributes:\n label: 请详细告知你的新点子（Nice Ideas）：\n placeholder: |\n 1. 您期望能够实现什么功能。\n\n 2. 您的理由（如：我一直被什么问题困扰……）。\n 如果方便的话，请提供截屏或者视频等详细信息。\n\n 3. 我能够做一些什么（最好是能提供一些伪代码帮助实现）。\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/feature-request.yml", "content": "name: 💡 Feature Request For Eggjs\ndescription: I have a suggestion (and may want to implement it)!\nlabels: [feature request]\nbody:\n - type: markdown\n attributes:\n value: |\n You have an idea how to improve the Eggjs?\n\n Before submitting, please have a look at the existing issues if there's already\n something related to your suggestion.\n - type: textarea\n attributes:\n label: 'Enter your suggestions in details:'\n placeholder: |\n 1. What I expected to happen?\n\n 2. Your reason (e.g: I'm always frustrated with...).\n If possible, images or videos are welcome.\n\n 3. What I plan to do (Optional but better in pseudo codes).\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/rfc-cn.yml", "content": "name: 🚀 RFC 提案\ndescription: 我对 Eggjs 框架技术架构功能层面上有重大新增、改进等。\nlabels: [RFC proposal]\nbody:\n - type: markdown\n attributes:\n value: |\n 对于 Eggjs 框架功能你是否有重大的新增或改进之类的想法？\n\n 不过在提交你的新想法或方案之前，麻烦请检阅一下是否之前的帖子中有类似重复的内容。\n - type: textarea\n attributes:\n label: 请详细告知你的新解决思路（Your new RFCs）：\n placeholder: |\n 1. 描述你希望解决的问题的现状，附上相关的 issue 地址。\n 如果方便的话，请提供截屏或者视频等详细信息。\n\n 2. 我能够做一些什么（譬如具体相关的的 API，描述思路，最好是能提供一些伪代码帮助实现）。\n validations:\n required: true\n - type: checkboxes\n attributes:\n label: '跟进类型（Follow-up Types）：'\n description: 此议案跟进类型情况：\n options:\n - label: 这是某个任务\n - label: 这是一个具体的 PR 的地址（URL）\n" }, { "path": ".github/ISSUE_TEMPLATE/rfc.yml", "content": "name: 🚀 RFC Proposals\ndescription: I've got a major improvement (or idea) on the technical architecture of the Eggjs framework.\nlabels: [RFC proposal]\nbody:\n - type: markdown\n attributes:\n value: |\n Any better new/changable functions for the core technical architecture of the Egg.js framework?\n\n But please make sure there's no duplicated issues related to your idea before submitting.\n - type: textarea\n attributes:\n label: 'Please describe your idea in detail:'\n placeholder: |\n 1. Describe the current situation of the problem you want to solve,\n and attach the related issue address.\n\n If it is possible, please provide screenshots or videos in detail.\n\n 2. What can I do (related APIs, Your ideas, better to provide some pseudo code to help implementations).\n validations:\n required: true\n - type: checkboxes\n attributes:\n label: Follow-up type\n description: The type of the RFC proposals.\n options:\n - label: Some Task\n - label: PR URL(s)\n validations:\n required: true\n" }, { "path": ".github/actions/clone/action.yml", "content": "name: 'Clone Repositories'\ndescription: 'Clone self and upstream repositories'\n\ninputs:\n ecosystem-ci-project:\n description: 'The ecosystem ci project to clone'\n required: false\n default: ''\n\nruns:\n using: 'composite'\n steps:\n - name: Output ecosystem ci project hash\n shell: bash\n id: ecosystem-ci-project-hash\n if: ${{ inputs.ecosystem-ci-project != '' }}\n run: |\n node -e \"const fs = require('fs'); const data = JSON.parse(fs.readFileSync('./ecosystem-ci/repo.json', 'utf8')); const project = data['${{ inputs.ecosystem-ci-project }}']; console.log('ECOSYSTEM_CI_PROJECT_HASH=' + project.hash);\" >> $GITHUB_OUTPUT\n node -e \"const fs = require('fs'); const data = JSON.parse(fs.readFileSync('./ecosystem-ci/repo.json', 'utf8')); const project = data['${{ inputs.ecosystem-ci-project }}']; console.log('ECOSYSTEM_CI_PROJECT_REPOSITORY=' + project.repository.replace('https://github.com/', '').replace('.git', ''));\" >> $GITHUB_OUTPUT\n\n - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6\n if: ${{ inputs.ecosystem-ci-project != '' }}\n with:\n repository: ${{ steps.ecosystem-ci-project-hash.outputs.ECOSYSTEM_CI_PROJECT_REPOSITORY }}\n path: ecosystem-ci/${{ inputs.ecosystem-ci-project }}\n ref: ${{ steps.ecosystem-ci-project-hash.outputs.ECOSYSTEM_CI_PROJECT_HASH }}\n" }, { "path": ".github/copilot-instructions.md", "content": "# Eggjs Framework - GitHub Copilot Development Instructions\n\n**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.**\n\n## Overview\n\nEggjs 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.\n\nThis is a **pnpm monorepo** with multiple packages using pnpm workspaces and catalog mode for centralized dependency management.\n\n## Prerequisites and Environment Setup\n\n- **Node.js >= 20.19.0 required** - This is a hard requirement\n- Enable pnpm first: `corepack enable pnpm` (installs pnpm v10.16.0)\n- **NEVER CANCEL** any build or test commands - they can take several minutes to complete\n\n## Bootstrap and Build Process\n\n**Always run these commands in sequence after fresh clone:**\n\n```bash\n# 1. Enable pnpm (required first)\ncorepack enable pnpm\n\n# 2. Install all dependencies - takes ~63 seconds. NEVER CANCEL. Set timeout to 120+ seconds.\npnpm install\n\n# 3. Build all packages - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.\npnpm run build\n\n# 4. Run linting (optional but recommended) - takes ~2 seconds\npnpm run lint\n```\n\n## Monorepo Structure\n\n### Key Packages (all in `packages/` directory)\n\n- **`packages/egg/`** - Main Eggjs framework (TypeScript, uses tsdown for builds)\n- **`packages/core/`** - Core plugin framework\n- **`packages/utils/`** - Utility functions\n- **`packages/mock/`** - Testing utilities\n- **`packages/cluster/`** - Cluster management\n- **`packages/koa/`** - Koa web framework\n- **`packages/supertest/`** - HTTP testing utilities\n- **`packages/extend2/`** - Object extension utility\n\n### Supporting Directories\n\n- **`examples/`** - Two example apps: `helloworld-commonjs` and `helloworld-typescript` (currently have runtime issues)\n- **`site/`** - Documentation website built with Dumi\n\n## Essential Commands and Timing\n\n### Build Commands\n\n- `pnpm run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**\n- `pnpm run clean` - Clean all dist directories\n\n### Testing Commands\n\n- `pnpm run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n- `pnpm run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n- `pnpm run ci` - **Run test coverage + build (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**\n\n### Linting Commands\n\n- `pnpm run lint` - Run oxlint across all packages (~2 seconds)\n\n### Documentation Commands\n\n- `pnpm run site:dev` - Start documentation dev server at http://localhost:8000\n- `cd site && pnpm run build:skip` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**\n\n### Example Applications (Currently Not Working)\n\n- `pnpm run example:commonjs` - Start CommonJS example (has runtime issues)\n- `pnpm run example:typescript` - Start TypeScript example (has runtime issues)\n\n## Package-Specific Commands\n\nRun commands for specific packages using `pnpm --filter=`:\n\n```bash\n# Examples\npnpm --filter=egg run test\npnpm --filter=@eggjs/core run build\npnpm --filter=site run dev\n```\n\n## Development Workflow\n\n### 1. Making Changes\n\n- Always build packages first: `pnpm run build`\n- Work primarily in `packages/egg/src/` for core framework features\n- Use TypeScript throughout - all packages are TypeScript-based\n- Follow the existing directory conventions in `packages/egg/src/`:\n - `lib/` - Core classes (Application, Agent, EggApplicationCore)\n - `app/extend/` - Framework extensions (context, helper, request, response)\n - `config/` - Default configurations and plugins\n - `lib/core/` - Core components (httpclient, logger, messenger)\n - `lib/loader/` - Application loaders\n\n### 2. Validation Steps\n\n**Always perform these validation steps after making changes:**\n\n```bash\n# 1. Build all packages (required)\npnpm run build\n\n# 2. Run linting\npnpm run lint\n\n# 3. Run tests (some failures are expected in fresh environment)\npnpm run test\n\n# 4. Test documentation site\npnpm run site:dev\n```\n\n### 3. Testing Strategy\n\n- **All packages use Vitest for testing** - this is the standard test runner\n- Test files follow pattern: `test/**/*.test.ts`\n- Use `import { describe, it } from 'vitest'` for test functions\n- Use Node.js built-in `assert` module for assertions\n- Create test fixtures in `packages/egg/test/fixtures/apps/` for scenario testing\n\n## Key Framework Concepts\n\n### Architecture\n\n- **EggApplicationCore** - Base application class with core functionality\n- **Application** - Main app class for worker processes\n- **Agent** - Agent process class for background tasks\n- **Context** - Extended Koa context with Egg-specific features\n- **BaseContextClass** - Base for controllers, services, subscriptions\n\n### Loading Convention (Automatic Discovery Order)\n\n1. Plugin system\n2. Configurations\n3. Application/Request/Response/Context extensions\n4. Custom loaders\n5. Services\n6. Middlewares\n7. Controllers\n8. Router\n\n### Cluster vs Single Mode\n\n- **Cluster Mode** (default) - Multi-process with master, agent, and worker processes\n- **Single Mode** - Single process for development/testing\n\n## Working with TypeScript\n\n- All packages use strict TypeScript mode\n- Uses tsdown for unbundled ESM builds (preserves file structure)\n- Each package has `tsdown.config.ts` for build configuration\n- **All sub-project tsconfig.json files MUST extend from root:** `\"extends\": \"../../tsconfig.json\"`\n- Root tsconfig.json includes all packages in `references` array\n\n## pnpm Workspace & Catalog Dependencies\n\n- Dependencies defined in `pnpm-workspace.yaml` catalog section\n- Reference catalog entries: `\"package-name\": \"catalog:\"`\n- Internal workspace dependencies: `\"package-name\": \"workspace:*\"`\n- This ensures consistent versions across all packages\n\n## Common Issues and Troubleshooting\n\n### Test Failures\n\n- Some tests may fail in fresh environments - this is normal\n- Focus on fixing only failures related to your changes\n- Examples may have runtime issues - don't use them for validation\n\n### Build Issues\n\n- Always run `pnpm run build` after making changes\n- TypeScript compilation errors will show clearly\n- Build warnings are generally acceptable\n\n### ESM/CommonJS Issues\n\n- Framework supports both ESM and CommonJS\n- Main package exports both formats\n- If you see \"ERR_UNKNOWN_FILE_EXTENSION\" errors, ensure packages are built first\n\n## File Locations Reference\n\n### Key Configuration Files\n\n- `pnpm-workspace.yaml` - Workspace and catalog configuration\n- `package.json` - Root monorepo scripts and devDependencies\n- `packages/egg/package.json` - Main framework package configuration\n- `packages/egg/tsdown.config.ts` - Build configuration\n- `packages/egg/src/config/plugin.ts` - Built-in plugin configurations\n- `packages/egg/src/config/config.default.ts` - Default framework configuration\n\n### Important Source Files\n\n- `packages/egg/src/lib/application.ts` - Main Application class\n- `packages/egg/src/lib/agent.ts` - Agent process manager\n- `packages/egg/src/lib/egg.ts` - Core EggApplicationCore\n- `packages/egg/src/lib/start.ts` - Application startup logic\n- `packages/egg/src/lib/loader/` - Convention-based loaders\n\n### Build Outputs\n\n- `packages/*/dist/` - Built JavaScript and TypeScript definitions\n- `site/dist/` - Built documentation site\n\n## Validation Scenarios\n\nAfter making changes, always verify:\n\n1. **Build Success**: `pnpm run build` completes without errors\n2. **Linting Passes**: `pnpm run lint` shows no new errors\n3. **Documentation Loads**: `pnpm run site:dev` starts successfully and site loads at http://localhost:8000\n4. **Tests Run**: `pnpm run test` executes (some failures expected, focus on your changes)\n\n**Remember**: This is a complex enterprise framework. Always build first, validate incrementally, and focus on the core packages (`egg`, `core`, `utils`) for most development work.\n\n## Commit Message Format\n\n**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.**\n\n### Required Format Structure\n\n```\n(): \n\n\n\n