Espacio de trabajo
pnpm tiene soporte incorporado para monorepos (también conocidos como repositorios de paquetes múltiples, repositorios de proyectos múltiples o repositorios monolíticos). Puede crear un espacio de trabajo para unir varios proyectos dentro de un único repositorio.
A workspace must have a pnpm-workspace.yaml file in its root.
tip
If you are looking into monorepo management, you might also want to look into Bit. Bit usa pnpm en su interior, pero automatiza muchas de las cosas que actualmente se hacen manualmente en un espacio de trabajo tradicional administrado por pnpm/npm/Yarn. There's an article about bit install that talks about it: Painless Monorepo Dependency Management with Bit.
Protocolo de espacio de trabajo (workspace:)#
If linkWorkspacePackages is set to true, pnpm will link packages from the workspace if the available packages match the declared ranges. Por ejemplo, foo@1.0.0 está vinculado a bar si bar tiene "foo": "^1.0.0" en sus dependencias y foo@1.0.0 está en el espacio de trabajo. Sin embargo, si bar tiene "foo": "2.0.0" en las dependencias y foo@2.0.0 no está en el espacio de trabajo, entonces foo@2.0.0 se instalará desde el registro. Este comportamiento presenta algo de incertidumbre.
Afortunadamente, pnpm admite el protocolo workspace:. Cuando se usa este protocolo, pnpm se negará a resolver cualquier cosa que no sea un paquete de espacio de trabajo local. Por lo tanto, si establece "foo": "workspace: 2.0.0", esta vez la instalación fallará porque " foo@2.0.0 " no está presente en el espacio de trabajo.
This protocol is especially useful when the linkWorkspacePackages option is set to false. En ese caso, pnpm solo vinculará paquetes desde el espacio de trabajo si se usa el protocolo workspace:.
Referenciando paquetes de espacio de trabajo a través de alias#
Supongamos que tiene un paquete en el espacio de trabajo llamado foo. Por lo general, lo referenciaría como "foo": "workspace:*".
Si desea utilizar un alias diferente, la siguiente sintaxis también funcionará: "bar": "workspace:foo@*".
Antes de publicar, los alias se convierten en dependencias con alias regulares. El ejemplo anterior se convertirá en: "bar": "npm:foo@1.0.0".
Referenciando paquetes de espacio de trabajo a través de su ruta relativa#
En un espacio de trabajo con 2 paquetes:
+ packages
+ foo
+ bar
bar puede tener foo en sus dependencias declaradas como "foo": "workspace:../foo". Antes de publicar, estas especificaciones se convierten a las especificaciones de versión regular soportadas por todos los gestores de paquetes.
Publicando paquetes del espacio de trabajo#
Cuando un paquete de espacio de trabajo se empaqueta en un archivo (ya sea a través de pnpm pack o uno de los comandos de publicación como pnpm publique), reemplazamos dinámicamente cualquier dependencia de workspace: por:
- The corresponding version in the target workspace (if you use
workspace:,workspace:*,workspace:~, orworkspace:^) - El rango de versión semántica asociado (para cualquier otro tipo de rango)
A bare workspace: without a version range is treated as workspace:*.
Así, por ejemplo, si tenemos foo, bar, qar, zoo en el espacio de trabajo y todos están en la versión 1.5.0, lo siguiente:
{
"dependencies": {
"foo": "workspace:*",
"bar": "workspace:~",
"qar": "workspace:^",
"zoo": "workspace:^1.5.0"
}
}
Será transformado en:
{
"dependencies": {
"foo": "1.5.0",
"bar": "~1.5.0",
"qar": "^1.5.0",
"zoo": "^1.5.0"
}
}
Esta característica le permite depender de sus paquetes espacios de trabajo locales mientras aún puede publicar los paquetes resultantes en el registro remoto sin necesidad de pasos intermedios de publicación. Sus consumidores podrán utilizar sus espacios de trabajo publicados como cualquier otro paquete, beneficiándose de las garantías que ofrece el versionado semántico.
Flujo de trabajo de lanzamiento#
Versionar paquetes dentro de un espacio de trabajo es una tarea compleja y pnpm actualmente no proporciona una solución integrada para ello. Sin embargo, existen 2 herramientas bien probadas que manejan el control de versiones y admiten pnpm:
For how to set up a repository using Rush, read this page.
For using Changesets with pnpm, read this guide.
Resolución de problemas#
pnpm no puede garantizar que los scripts se ejecuten en orden topológico si existen ciclos entre las dependencias del espacio de trabajo. Si pnpm detecta dependencias cíclicas durante la instalación, generará una advertencia. Si pnpm puede averiguar qué dependencias están causando los ciclos, también las mostrará.
Si ve el mensaje There are cyclic workspace dependencies, inspeccione las dependencias de espacio de trabajo declaradas en dependencies, optionalDependencies y devDependencies.
Ejemplos de uso#
Estos son algunos de los proyectos de código abierto más populares que utilizan la función de espacio de trabajo de pnpm:
Configuración#
linkWorkspacePackages#
- Por defecto: false
- Tipo: true, false, deep
If this is enabled, locally available packages are linked to node_modules instead of being downloaded from the registry. This is very convenient in a monorepo. Si necesita que los paquetes locales también se vinculen a las subdependencias, usar la configuración deep.
Else, packages are downloaded and installed from the registry. However, workspace packages can still be linked by using the workspace: range protocol.
Packages are only linked if their versions satisfy the dependency ranges.
injectWorkspacePackages#
- Por defecto: false
- Tipo: Boolean
Enables hard-linking of all local workspace dependencies instead of symlinking them. Alternatively, this can be achieved using dependenciesMeta[].injected, which allows to selectively enable hard-linking for specific dependencies.
note
Even if this setting is enabled, pnpm will prefer to deduplicate injected dependencies using symlinks—unless multiple dependency graphs are required due to mismatched peer dependencies. This behaviour is controlled by the dedupeInjectedDeps setting.
dedupeInjectedDeps#
- Por defecto: true
- Tipo: Boolean
When this setting is enabled, dependencies that are injected will be symlinked from the workspace whenever possible. If the dependent project and the injected dependency reference the same peer dependencies, then it is not necessary to physically copy the injected dependency into the dependent's node_modules; a symlink is sufficient.
syncInjectedDepsAfterScripts#
Agregado en: v10.5.0
- Predeterminado: indefinido
- Type: String[]
Injected workspace dependencies are collections of hardlinks, which don't add or remove the files when their sources change. This causes problems in packages that need to be built (such as in TypeScript projects).
This setting is a list of script names. When any of these scripts are executed in a workspace package, the injected dependencies inside node_modules will also be synchronized.
preferWorkspacePackages#
- Por defecto: false
- Tipo: Boolean
If this is enabled, local packages from the workspace are preferred over packages from the registry, even if there is a newer version of the package in the registry.
This setting is only useful if the workspace doesn't use saveWorkspaceProtocol.
sharedWorkspaceLockfile#
- Por defecto: true
- Tipo: Boolean
If this is enabled, pnpm creates a single pnpm-lock.yaml file in the root of the workspace. This also means that all dependencies of workspace packages will be in a single node_modules (and get symlinked to their package node_modules folder for Node's module resolution).
Advantages of this option:
- cada dependencia es un singleton
- instalaciones más rápidas en un monorepo
- menos cambios en las revisiones de código, ya que están todos en un solo archivo
note
Even though all the dependencies will be hard linked into the root node_modules, packages will have access only to those dependencies that are declared in their package.json, so pnpm's strictness is preserved. This is a result of the aforementioned symbolic linking.
saveWorkspaceProtocol#
- Default: rolling
- Tipo: true, false, rolling
Esta configuración controla cómo se agregan las dependencias que están vinculadas desde el espacio de trabajo a package.json.
Si foo@1.0.0 está en el espacio de trabajo y ejecuta pnpm add foo en otro proyecto del espacio de trabajo, a continuación se muestra cómo se agregará foo al campo de dependencias. The savePrefix setting also influences how the spec is created.
| saveWorkspaceProtocol | savePrefix | especificaciones |
|---|---|---|
| falso | '' |
1.0.0 |
| falso | '~' |
~1.0.0 |
| falso | '^' |
^1.0.0 |
| true | '' |
workspace:1.0.0 |
| true | '~' |
workspace:~1.0.0 |
| true | '^' |
workspace:^1.0.0 |
| rolling | '' |
workspace:* |
| rolling | '~' |
workspace:~ |
| rolling | '^' |
workspace:^ |
includeWorkspaceRoot#
- Por defecto: false
- Tipo: Boolean
Al ejecutar comandos recursivamente en un espacio de trabajo, ejecútelos también en el proyecto del espacio de trabajo raíz.
ignoreWorkspaceCycles#
- Por defecto: false
- Tipo: Boolean
When set to true, no workspace cycle warnings will be printed.
disallowWorkspaceCycles#
- Por defecto: false
- Tipo: Boolean
When set to true, installation will fail if the workspace has cycles.
failIfNoMatch#
- Por defecto: false
- Tipo: Boolean
When set to true, the CLI will exit with a non-zero code if no packages match the provided filters.
For example, the following command will exit with a non-zero code because bad-pkg-name is not present in the workspace:
pnpm --filter=bad-pkg-name test