The egg supports three package managers — npm, pnpm, and yarn — and can detect the right one automatically from your lockfile. You control this behavior with the PACKAGE_MANAGER variable.
Auto-Detection
When PACKAGE_MANAGER is set to auto (the default), the egg inspects your project’s lockfile at startup to decide which manager to use:
| Lockfile present | Manager selected |
|---|
pnpm-lock.yaml | pnpm |
yarn.lock | yarn |
| Neither | npm |
pnpm takes priority over yarn in the detection order. If your repository contains both pnpm-lock.yaml and yarn.lock for any reason, the egg will select pnpm.
Overriding the Package Manager
Set PACKAGE_MANAGER to npm, pnpm, or yarn to force a specific manager regardless of which lockfiles are present. This is useful when:
- Your lockfile is absent from the repository (e.g. it is in
.gitignore)
- You want to enforce a consistent manager across environments
- Auto-detection is picking the wrong manager
You can change this variable from the Startup tab of your server in the panel. Restart the server after saving for the change to take effect.
Install Behavior by Manager
The egg checks whether package-lock.json exists in your project root:
- Lockfile present — runs
npm ci, which installs exactly the versions recorded in package-lock.json. This is deterministic and will fail if the lockfile is out of sync with package.json.
- No lockfile — runs
npm install, which resolves dependencies from package.json and generates a fresh lockfile.
npm ci will fail if your package-lock.json is out of sync with package.json. This typically happens after manually editing package.json without running npm install locally. Commit an up-to-date lockfile to your repository to avoid this, or delete package-lock.json so the egg falls back to npm install.
pnpm is installed automatically via npm install -g pnpm if it is not already present in the container.The egg first attempts pnpm install --frozen-lockfile, which installs exactly what is recorded in pnpm-lock.yaml and refuses to update it. If that fails (for example, because no lockfile is present), it falls back to pnpm install.
yarn is installed automatically via npm install -g yarn if it is not already present in the container.The egg first attempts yarn install --frozen-lockfile, which installs from yarn.lock without modifying it. If that fails (for example, because no lockfile is present), it falls back to yarn install.
Deterministic Installs
Commit your lockfile (package-lock.json, pnpm-lock.yaml, or yarn.lock) to your repository. This ensures the egg installs the exact same dependency versions on every startup — across your local machine, CI, and the panel server — eliminating “works on my machine” issues.
- Dependencies never silently upgrade between server restarts.
- If a dependency is added to
package.json but the lockfile is not updated, the install will fail loudly rather than silently installing an unexpected version.
To update your dependencies intentionally, update the lockfile locally and push the change to your repository. The egg will pick up the updated lockfile on the next startup (with AUTO_UPDATE=1) or on the next manual restart after you push. 