Skip to content

chore(repo): switch package manager references from pnpm to utoo #5961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
killagu wants to merge 14 commits into
base: next
Choose a base branch
from
+151 −124
Open

chore(repo): switch package manager references from pnpm to utoo #5961

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ab76d57
chore(repo): switch package manager references from pnpm to utoo
killagu Jun 2, 2026
26b1a40
fix(ci,docs): drop unsupported PUBLINT_PACK value, sync utoo/node ver…
killagu Jun 2, 2026
8a96e3e
chore(repo): address CodeRabbit review feedback
killagu Jun 2, 2026
a0c2ddf
fix(ci): replace unsupported `utoo -r pack` with per-package npm pack
killagu Jun 2, 2026
585d981
fix(docs,scripts): use \`ut\` CLI alias and real script names
killagu Jun 2, 2026
80b413b
fix(ci): restore pnpm for E2E pack step
killagu Jun 2, 2026
f88b87b
fix(ci): pin pnpm version in E2E setup-pnpm action
killagu Jun 2, 2026
2a4c085
docs: fix script descriptions and prepend corepack bootstrap
killagu Jun 2, 2026
38ee2ad
fix(ci): disable pnpm's packageManager strict check for the pack step
killagu Jun 2, 2026
e38249c
docs: fix \`ut test\` → \`ut run test\` and Dumi → VitePress reference
killagu Jun 2, 2026
5f8b4c3
fix(ci): move pnpm setup after \`ut install\` to avoid SIGPIPE
killagu Jun 2, 2026
842a307
ci: retry \`ut install\` up to 3 times for transient SIGPIPE (141)
killagu Jun 2, 2026
c522197
fix(ci): use correct env name for pnpm packageManager strict bypass
killagu Jun 2, 2026
5c856b3
fix(ci): run \`pnpm install\` before \`pnpm -r pack\` so workspace de…
killagu Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 34 additions & 34 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,30 @@

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 **pnpm monorepo** with multiple packages using pnpm workspaces and catalog mode for centralized dependency management.
This is a **utoo monorepo** with multiple packages using utoo workspaces and catalog mode for centralized dependency management.

## Prerequisites and Environment Setup

- **Node.js >= 20.19.0 required** - This is a hard requirement
- Enable pnpm first: `corepack enable pnpm` (installs pnpm v10.16.0)
- **Node.js >= 22.18.0 required** - This is a hard requirement
- Enable utoo first: `corepack enable utoo` (installs utoo v1.0.28)
- **NEVER CANCEL** any build or test commands - they can take several minutes to complete

## Bootstrap and Build Process

**Always run these commands in sequence after fresh clone:**

```bash
# 1. Enable pnpm (required first)
corepack enable pnpm
# 1. Enable utoo (required first)
corepack enable utoo

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

# 3. Build all packages - takes ~14 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
pnpm run build
ut run build

# 4. Run linting (optional but recommended) - takes ~2 seconds
pnpm run lint
ut run lint
```

## Monorepo Structure
Expand All @@ -48,51 +48,51 @@ pnpm run lint
### Supporting Directories

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

## Essential Commands and Timing

### Build Commands

- `pnpm run build` - **Build all packages (~14 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
- `pnpm run clean` - Clean all dist directories
- `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

- `pnpm run test` - **Run all tests (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
- `pnpm run test:cov` - **Run tests with coverage (~2 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
- `pnpm run ci` - **Run test coverage + build (~2.1 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**
- `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 minutes). NEVER CANCEL. Set timeout to 180+ seconds.**

### Linting Commands

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

### Documentation Commands

- `pnpm run site:dev` - Start documentation dev server at http://localhost:8000
- `cd site && pnpm run build:skip` - **Build documentation site (~24 seconds). NEVER CANCEL. Set timeout to 60+ seconds.**
- `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)

- `pnpm run example:commonjs` - Start CommonJS example (has runtime issues)
- `pnpm run example:typescript` - Start TypeScript example (has runtime issues)
- `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 `pnpm --filter=<package>`:
Run commands for specific packages using `ut --filter=<package>`:

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

## Development Workflow

### 1. Making Changes

- Always build packages first: `pnpm run build`
- Always build packages first: `ut run build`
- 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/`:
Expand All @@ -108,16 +108,16 @@ pnpm --filter=site run dev

```bash
# 1. Build all packages (required)
pnpm run build
ut run build

# 2. Run linting
pnpm run lint
ut run lint

# 3. Run tests (some failures are expected in fresh environment)
pnpm run test
ut run test

# 4. Test documentation site
pnpm run site:dev
ut run site:dev
```

### 3. Testing Strategy
Expand Down Expand Up @@ -162,7 +162,7 @@ pnpm run site:dev
- **All sub-project tsconfig.json files MUST extend from root:** `"extends": "../../tsconfig.json"`
- Root tsconfig.json includes all packages in `references` array

## pnpm Workspace & Catalog Dependencies
## utoo Workspace & Catalog Dependencies

- Dependencies defined in `pnpm-workspace.yaml` catalog section
- Reference catalog entries: `"package-name": "catalog:"`
Expand All @@ -179,7 +179,7 @@ pnpm run site:dev

### Build Issues

- Always run `pnpm run build` after making changes
- Always run `ut run build` after making changes
- TypeScript compilation errors will show clearly
- Build warnings are generally acceptable

Expand Down Expand Up @@ -217,10 +217,10 @@ pnpm run site:dev

After making changes, always verify:

1. **Build Success**: `pnpm run build` completes without errors
2. **Linting Passes**: `pnpm run lint` shows no new errors
3. **Documentation Loads**: `pnpm run site:dev` starts successfully and site loads at http://localhost:8000
4. **Tests Run**: `pnpm run test` executes (some failures expected, focus on your changes)
1. **Build Success**: `ut run build` completes without errors
2. **Linting Passes**: `ut run lint` shows no new errors
3. **Documentation Loads**: `ut run site:dev` starts successfully and the printed VitePress URL responds
4. **Tests Run**: `ut run test` executes (some failures expected, focus on your changes)

**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.

Expand Down
9 changes: 5 additions & 4 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ jobs:
node-version: '24'

- name: Install dependencies
run: ut install --from pnpm
# Retry to absorb transient `exit 141` (SIGPIPE) from `ut install`.
run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)

- name: Run lint
run: ut run lint
Expand Down Expand Up @@ -160,7 +161,7 @@ jobs:
node-version: ${{ matrix.node }}

- name: Install dependencies
run: ut install --from pnpm
run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)

- name: Run tests
run: ut run ci
Expand Down Expand Up @@ -204,7 +205,7 @@ jobs:
node-version: ${{ matrix.node }}

- name: Install dependencies
run: ut install --from pnpm
run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)

- name: Run tests
run: |
Expand Down Expand Up @@ -245,7 +246,7 @@ jobs:
node-version: ${{ matrix.node }}

- name: Install dependencies
run: ut install --from pnpm
run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)

- name: Run tests
run: |
Expand Down
37 changes: 28 additions & 9 deletions .github/workflows/e2e-test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,27 +141,46 @@ jobs:
with:
ecosystem-ci-project: ${{ matrix.project.name }}

- name: Install pnpm
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
- name: Install utoo
uses: utooland/setup-utoo@3a51006d0b66afcc32d1b9177a4b200b74f4a8cb # main

- name: Set up Node.js
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
with:
node-version: ${{ matrix.project.node-version }}

- name: Install dependencies
run: pnpm install --no-frozen-lockfile
run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)

- name: Build all packages
env:
# publint pack defaults to npm (main CI env has no pnpm); in E2E we
# already have pnpm installed and npm pack against pnpm's symlinked
# node_modules is ~10x slower, so prefer pnpm pack here
PUBLINT_PACK: pnpm
run: pnpm build
run: ut run build

- name: Install pnpm (for `pnpm -r pack`)
# utoo's `ut pm-pack` does not resolve `workspace:` / `catalog:`
# protocols inside the packed manifests, so downstream `npm install`
# in the ecosystem-ci projects fails with EUNSUPPORTEDPROTOCOL.
# Keep pnpm available just for the pack step. The explicit `version`
# is required because `packageManager` in package.json now points at
# utoo, so the action can't infer the pnpm version itself.
# Setup must come AFTER `ut install`: action-setup exports PNPM_HOME,
# which makes utoo's install path read pnpm config and crash with
# exit 141 (SIGPIPE).
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
with:
version: 10

- name: Pack packages into tgz
# `pnpm -r pack` resolves workspace:/catalog: deps in the emitted
# manifests, which `ut pm-pack` does not yet do. pnpm refuses to
# run when `packageManager` points at another tool, so disable
# that strict check for just this step. pnpm needs its own
# node_modules layout to resolve `workspace:` versions, so run
# `pnpm install --no-frozen-lockfile` first (cheap on top of the
# ut install since the deps are already in the global store).
env:
NPM_CONFIG_PACKAGE_MANAGER_STRICT: 'false'
run: |
pnpm install --no-frozen-lockfile --ignore-scripts
pnpm -r pack

- name: Override dependencies from tgz in ${{ matrix.project.name }}
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ jobs:
fetch-depth: 0
token: ${{ secrets.GIT_TOKEN }}

- name: Setup pnpm
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
- name: Setup utoo
uses: utooland/setup-utoo@3a51006d0b66afcc32d1b9177a4b200b74f4a8cb # main

- name: Setup Node.js
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
Expand All @@ -72,7 +72,7 @@ jobs:
registry-url: 'https://registry.npmjs.org'

- name: Install dependencies
run: pnpm install --no-frozen-lockfile
run: ut install --from pnpm
Comment on lines 74 to +75
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jun 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add retry parity for ut install in release workflow.

Line 75 is a single-attempt install, while the same command was made retry-safe in other workflows for transient failures. This can cause avoidable manual release failures.

Suggested fix 
-      - name: Install dependencies
-        run: ut install --from pnpm
+      - name: Install dependencies
+        # Retry to absorb transient `exit 141` (SIGPIPE) from `ut install`.
+        run: ut install --from pnpm || (sleep 5 && ut install --from pnpm) || (sleep 10 && ut install --from pnpm)
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/release.yml at line 75, The workflow step currently calls
the single-attempt command "ut install --from pnpm"; make it retry-safe to match
other workflows by replacing that invocation with the retry wrapper used
elsewhere (e.g., "ut retry install --from pnpm" or the project’s standard retry
helper), so transient failures are retried automatically; update the step that
runs "ut install --from pnpm" to use the retry variant.


- name: Configure Git
run: |
Expand Down Expand Up @@ -149,7 +149,7 @@ jobs:
git push origin ${{ github.event.inputs.branch }} --tags

- name: Run build
run: pnpm build
run: ut run build

- name: Publish packages (dry run)
if: ${{ github.event.inputs.dry_run == 'true' }}
Expand Down
17 changes: 9 additions & 8 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ If another agent-specific file exists, it should import or defer to this file fo

## Project Map

Egg is maintained as a pnpm monorepo.
Egg is maintained as a utoo monorepo.

- `packages/` contains core framework packages and shared internals.
- `plugins/` contains optional Egg integrations.
Expand All @@ -18,12 +18,13 @@ Egg is maintained as a pnpm monorepo.

## Core Commands

- `pnpm install` hydrates the workspace.
- `pnpm run build` builds all packages.
- `pnpm run test` runs the main test suite.
- `pnpm run lint` runs linting.
- `pnpm run typecheck` runs TypeScript checking.
- use filtered commands for focused work, for example `pnpm --filter=egg run test` or `pnpm --filter=site run dev`.
- `corepack enable utoo` enables the pinned utoo version on a clean machine.
- `ut install` hydrates the workspace.
- `ut run build` builds all packages.
- `ut run test` runs the main test suite.
- `ut run lint` runs linting.
- `ut run typecheck` runs TypeScript checking.
- use filtered commands for focused work, for example `ut --filter=egg run test` or `ut --filter=site run dev`.

### Local CI

Expand Down Expand Up @@ -65,7 +66,7 @@ Then re-run tests.

- review `SECURITY.md` before handling vulnerability-related work
- do not commit secrets, credentials, or local-only URLs
- keep local Node.js and pnpm versions aligned with the repository configuration
- keep local Node.js and utoo versions aligned with the repository configuration

## Shared Knowledge Workflow

Expand Down
Loading
Loading