Zoltan Kochan
b3eee14a96
Part of pnpm/tasks#191. Wrong claims, fixed on the v12 page and on the v11 twin where it had the same text: - audit: `--interactive` implies `--fix=override`; `info` is a valid audit level. - change check validates the pending intents. - deploy copies the publish packlist unless `deployAllFiles` is set. - deprecate: an empty message fails, use `pnpm undeprecate`. - deprecate, dist-tag: only `--otp` supplies the one-time password. - dist-tag add defaults to `latest`, not the `tag` setting. - docs takes exactly one package. - env: there is no `add` subcommand, and `list` queries the Node.js mirror only. - v12 only: clean no longer says it uses Node.js, add no longer presents `-w` as an alias, the deploy package-manager-pin history is no longer contradictory, doctor sample shows store v11. Missing facts: - add: `--save-prefix`, `--save-build`, `--no-save-peer`, `--no-save-types`, `--lockfile-only`, `--force`; where Yarn vs npm and Bun pins go; catalog and configDependencies links. - access status shorthands; approve-builds error codes, the placeholder value and the immediate rebuild; audit exit code, `--optional`, `--production`, and how to make `--ignore` write `audit.ignore`; `--ignore` exits with code 0 and `--ignore-unfixable` fails on an advisory without a GHSA ID. - bugs and docs `--registry`; ci accepts install options; clean script override and modulesDir; config `--location` type and `get` output; create name mapping, `--shell-mode`, `--cpu`, `--os`, `--libc`; dedupe flags; deploy error codes and Dockerfile WORKDIR; dist-tag aliases and web OTP; env `--global` requirement; exec recursive options and PNPM_PACKAGE_NAME; fetch `--ignore-pnpmfile`, lockfile requirement, optional pnpmfile in the Dockerfiles. - usage, examples, and output for bin, cache, cache list, cache delete (with the no-argument warning), cache view, cat-file, cat-index, find-hash, ignored-builds, import, and init (`initPackageManager`, `initType`, ERR_PNPM_PACKAGE_JSON_EXISTS). Stale history on v12 pages: removed "Added in" markers for v10 and v11 and rewrote "Since v11..." passages as current behavior in access, add, approve-builds, audit, bugs, cache-list-registries, cache-path, cache-prune, change, ci, config, create, deploy, deprecate, dist-tag, docs, doctor, help, ignored-builds, and init. Review follow-up: cat-file now says it rejects the hex digest that cat-index prints; the settings index links initPackageManager and initType; `change check` says it plans the release without reporting it (both versions); `pnpm bin` follows a custom modulesDir.
117 lines
5.2 KiB
Markdown
117 lines
5.2 KiB
Markdown
---
|
|
id: deploy
|
|
title: "pnpm deploy"
|
|
---
|
|
|
|
Deploy a package from a workspace. During deployment, the files of the deployed package are copied to the target directory. All dependencies of the deployed package, including dependencies from the workspace, are installed inside an isolated `node_modules` directory at the target directory. The target directory will contain a portable package that can be copied to a server and executed without additional steps.
|
|
|
|
:::note
|
|
|
|
Since v11.26.0, `pnpm deploy` no longer requires [`injectWorkspacePackages`](../workspaces.md#injectworkspacepackages). A linked workspace dependency is rewritten to a `file:` dependency in the dedicated deploy lockfile. The peer dependencies it declares are bound the way an injected install binds them: to the version its parent provides. If the parent does not depend on the peer, pnpm looks further up, to the deployed project. A peer that no ancestor provides is bound to the deployed graph's own resolution.
|
|
|
|
The binding is ambiguous when the ancestors provide more than one package or version, or when no ancestor provides the peer and the deployed graph holds more than one version. The deploy then fails with `ERR_PNPM_DEPLOY_AMBIGUOUS_PEER`, naming the package, the peer, and the competing resolutions. Pin the peer to one version with an [`overrides`](../settings/dependency-resolution.md#overrides) entry, or turn `injectWorkspacePackages` on, which is the setting that decides between the candidates.
|
|
|
|
Before v11.26.0 the command refused every non-injected workspace up front. `--legacy`, or `forceLegacyDeploy: true`, still selects the older implementation.
|
|
|
|
:::
|
|
|
|
:::note
|
|
|
|
When the [`enableGlobalVirtualStore`](../settings/node-modules.md#enableglobalvirtualstore) option is set, `pnpm deploy` ignores it and always creates a localized virtual store within the deploy directory. This keeps the deploy directory self-contained and portable.
|
|
|
|
:::
|
|
|
|
Usage:
|
|
|
|
```sh
|
|
pnpm --filter=<deployed project name> deploy <target directory>
|
|
```
|
|
|
|
In case you build your project before deployment, also use the `--prod` option to skip `devDependencies` installation.
|
|
|
|
```sh
|
|
pnpm --filter=<deployed project name> --prod deploy <target directory>
|
|
```
|
|
|
|
Usage in a docker image. After building everything in your monorepo, do this in a second image that uses your monorepo base image as a build context or in an additional build stage:
|
|
|
|
```dockerfile title="Dockerfile"
|
|
# syntax=docker/dockerfile:1.4
|
|
|
|
FROM workspace as pruned
|
|
RUN pnpm --filter <your package name> --prod deploy pruned
|
|
|
|
FROM node:22-alpine
|
|
WORKDIR /app
|
|
|
|
ENV NODE_ENV=production
|
|
|
|
COPY --from=pruned /app/pruned .
|
|
|
|
ENTRYPOINT ["node", "index.js"]
|
|
```
|
|
|
|
## Options
|
|
|
|
### --force
|
|
|
|
Allow deployment to a non-empty target directory. Without this flag, pnpm fails
|
|
with `ERR_PNPM_DEPLOY_DIR_NOT_EMPTY` if the target directory is not empty.
|
|
|
|
### --ignore-scripts
|
|
|
|
Skip lifecycle scripts during deployment, including dependency build scripts.
|
|
See [`pnpm install --ignore-scripts`](./install.md#--ignore-scripts).
|
|
|
|
### --dev, -D
|
|
|
|
Only `devDependencies` are installed.
|
|
|
|
### --no-optional
|
|
|
|
`optionalDependencies` are not installed.
|
|
|
|
### --prod, -P
|
|
|
|
Packages in `devDependencies` won't be installed.
|
|
|
|
### --filter <package_selector\>
|
|
|
|
[Read more about filtering.](../filtering.md)
|
|
|
|
### --legacy
|
|
|
|
Force legacy deploy implementation.
|
|
|
|
By default, `pnpm deploy` will try creating a dedicated lockfile from a shared lockfile for deployment. The `--legacy` flag disables this behavior and also allows using the deploy command without the `inject-workspace-packages=true` setting.
|
|
|
|
## Files included in the deployed project
|
|
|
|
By default, pnpm copies the files that `pnpm pack` would include. They are selected in _one_ of the following ways, resolved in order:
|
|
|
|
1. The project's `package.json` may contain a "files" field to list the files and directories that should be copied.
|
|
2. If there is an `.npmignore` file in the application directory then any files listed here are ignored.
|
|
3. If there is a `.gitignore` file in the application directory then any files listed here are ignored.
|
|
|
|
To copy every file of the project, set [`deployAllFiles`](../settings/other.md#deployallfiles) to `true`.
|
|
|
|
Since v11.28.0, symlinks that point to files or directories included in the deployed project are kept as symlinks.
|
|
|
|
## The deployed project
|
|
|
|
Since v11.28.0:
|
|
|
|
* The `packageManager` and `devEngines.packageManager` fields of the workspace root `package.json` are not copied into the deployed `package.json`. Versions v11.28.0 through v11.28.x copied them.
|
|
* The virtual store is created at [`virtualStoreDir`](../settings/node-modules.md#virtualstoredir), resolved against the deploy directory. A deploy from a shared lockfile records `virtualStoreDir` in the deployed `pnpm-workspace.yaml`. With the global virtual store enabled or an absolute `virtualStoreDir`, the deploy uses `node_modules/.pnpm`.
|
|
* The `prepare` script of the deployed project is not run.
|
|
* `--package-import-method` passed on the command line is respected.
|
|
|
|
## Configuration
|
|
|
|
### forceLegacyDeploy
|
|
|
|
* Default: **false**
|
|
* Type: **Boolean**
|
|
|
|
By default, `pnpm deploy` will try creating a dedicated lockfile from a shared lockfile for deployment. If this setting is set to `true`, the legacy `deploy` behavior will be used.
|