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.

Un espacio de trabajo debe tener un archivo pnpm-workspace.yaml en su raíz. Un espacio de trabajo también puede tener un .npmrc en su raíz.

tip

Si está indagando en la administración de monorepos, puede también darle un vistazo a 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. Existe un artículo acerca de bit install que habla sobre eso: Painless Monorepo Dependency Management with Bit.

Protocolo de espacio de trabajo (workspace:)

Por defecto, pnpm enlazará los paquetes desde el área de trabajo si los paquetes disponibles coinciden con los rangos declarados. 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.

Este protocolo es especialmente útil cuando la opción link-workspace-packages está en 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:

• La versión correspondiente en el espacio de trabajo de destino (si usa workspace:*, workspace:~ o workspace:^)
• El rango de versión semántica asociado (para cualquier otro tipo de rango)

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:

• changesets
• Rush.

Para saber cómo configurar un repositorio usando Rush, lea esta página.

Para usar Changesets con pnpm, lea esta guía.

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:

Proyecto	Estrellas	Fecha de migración	Commit de migración
Next.js		2022-05-29	f7b81316aea4fc9962e5e54981a6d559004231aa
Material UI		2024-01-03	a1263e3e5ef8d840252b4857f85b33caa99f471d
Vite		2021-09-26	3e1cce01d01493d33e50966d0d0fd39a86d229f9
Nuxt		2022-10-17	74a90c566c936164018c086030c7de65b26a5cb6
Vue 3.0		2021-10-09	61c5fbd3e35152f5f32e95bf04d3ee083414cecb
Astro		2022-03-08	240d88aefe66c7d73b9c713c5da42ae789c011ce
n8n		2022-11-09	736777385c54d5b20174c9c1fda38bb31fbf14b4
Prisma		2021-09-21	c4c83e788aa16d61bae7a6d00adc8a58b3789a06
Novu		2021-12-23	f2ea61f7d7ac7e12db4c9e70767082841ed98b2b
Slidev		2021-04-12	d6783323eb1ab1fc612577eb63579c8f7bc99c3a
Turborepo		2022-03-02	fd171519ec02a69c9afafc1bc5d9d1b481fba721
Element Plus		2021-09-23	f9e192535ff74d1443f1d9e0c5394fad10428629
NextAuth.js		2022-05-03	4f29d39521451e859dbdb83179756b372e3dd7aa
Ember.js		2023-10-18	b6b05da662497183434136fb0148e1dec544db04
Qwik		2022-11-14	021b12f58cca657e0a008119bc711405513e1ee9
VueUse		2021-09-25	826351ba1d9c514e34426c85f3d69fb9875c7dd9
SvelteKit		2021-09-26	b164420ab26fa04fd0fbe0ac05431f36a89ef193
Verdaccio		2021-09-21	9dbf73e955fcb70b0a623c5ab89649b95146c744
Vercel		2023-01-12	9c768b98b71cfc72e8638bf5172be88c39e8fa69
Vitest		2021-12-13	d6ff0ccb819716713f5eab5c046861f4d8e4f988
Cycle.js		2021-09-21	f2187ab6688368edb904b649bd371a658f6a8637
Milkdown		2021-09-26	4b2e1dd6125bc2198fd1b851c4f00eda70e9b913
Nhost		2022-02-07	10a1799a1fef2f558f737de3bb6cadda2b50e58f
Logto		2021-07-29	0b002e07850c8e6d09b35d22fab56d3e99d77043
Rollup plugins		2021-09-21	53fb18c0c2852598200c547a0b1d745d15b5b487
icestark		2021-12-16	4862326a8de53d02f617e7b1986774fd7540fccd
ByteMD		2021-02-18	36ef25f1ea1cd0b08752df5f8c832302017bb7fb