Paquetes scoped: @org/pkg, acceso y publishConfig

Un scope es más que un prefijo bonito: es un espacio de nombres que resuelve de golpe el problema del name squatting, agrupa paquetes bajo una identidad y decide a qué registro se enruta cada dependencia. Pero trae una trampa que tumba la primera publicación de casi todo el mundo: los paquetes con scope nacen privados. Entender el acceso, las organizaciones y publishConfig es lo que convierte esa fricción en una palanca de control.

Qué es un scope

Un scope es un prefijo con arroba que actúa como namespace: @acme/ui es el paquete ui dentro del scope @acme. Hay dos clases, indistinguibles en sintaxis pero distintas en gobernanza: el scope de usuario, que coincide con tu nombre en el registro, y el scope de organización, propiedad de una cuenta colectiva.

En disco, el scope se materializa como carpeta: un paquete con scope vive en node_modules/@acme/ui, no en la raíz plana de node_modules. Esa carpeta con arroba es la huella visible del namespace.

El valor estructural del scope se despliega en tres frentes que el espacio plano deja abiertos:

• Colisiones: @acme/parser y @otra/parser conviven sin disputarse el nombre global parser, un recurso escaso.
• Enrutado: un scope entero puede apuntar a otro registro desde el .npmrc, sin tocar el resto.
• Gobernanza: es la unidad natural sobre la que colgar permisos, equipos y doble factor.

Ese mapeo por scope es la costura que hace posible mezclar paquetes públicos y privados sin ambigüedad: @acme resuelve contra tu servidor interno mientras el resto sigue yendo al registro público.

# todo el scope @acme se resuelve contra un registro interno
@acme:registry=https://npm.acme.internal/
//npm.acme.internal/:_authToken=${ACME_TOKEN}

Acceso: público frente a restringido

Aquí está el escollo que sorprende a todos. Los paquetes sin scope son siempre públicos: no existe otra opción. Los paquetes con scope, en cambio, tienen acceso restricted (privado) por defecto.

El acceso se reduce a dos valores, y lo decisivo es que su defecto depende del scope:

• public: visible e instalable por cualquiera; único valor posible sin scope.
• restricted: privado; el defecto de los paquetes con scope, y exige plan de pago.

La consecuencia es brutalmente concreta: tu primer npm publish de un @tu-usuario/paquete falla con un 402 Payment Required o un 403, porque el registro asume que quieres publicarlo en privado y eso cuesta dinero.

La solución no es un plan de pago: es declarar explícitamente que lo quieres público. Ese único flag convierte el fallo en una publicación abierta y gratuita.

# publica un paquete con scope como publico y gratuito
npm publish --access public

# publicar como privado requiere una organizacion de pago
npm publish --access restricted

El flag --access public es lo que convierte un scope en un paquete abierto sin coste, y funciona igual para scopes de usuario y de organización. La lección de fondo es que el registro trata “con scope” como señal de intención privada, y te obliga a firmar de forma consciente la decisión de abrirlo: es más grave publicar algo privado por error que fallar al publicar algo público.

publishConfig: la publicación declarativa

Depender de recordar flags en cada publicación es frágil: un despiste y publicas con el acceso equivocado, o contra el registro equivocado. La forma robusta es declarativa.

El objeto publishConfig dentro de package.json fija, junto al código, cómo debe publicarse el paquete. Es la fuente de verdad versionada, revisable e inmune a los olvidos del terminal.

{
  "name": "@acme/ui",
  "version": "1.4.0",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/",
    "provenance": true
  }
}

Dentro de publishConfig caben las decisiones que no quieres dejar al azar:

• access: public o restricted, sin depender del flag.
• registry: el destino, para no publicar por error contra el registro equivocado.
• tag: el dist-tag por defecto de esta publicación —lo verás en la próxima lección—.
• provenance: activa la firma de procedencia desde CI.

Con esas claves en el manifiesto, el comando de publicación se queda desnudo: ya no necesita recordar ningún flag, porque cada decisión vive en el package.json.

# con publishConfig en el manifiesto, publicar no necesita flags
npm publish   # toma access, registry, tag y provenance del package.json

Llevar estas decisiones del terminal efímero al manifiesto versionado las vuelve documentadas y reproducibles: quien clone el repositorio publica igual que tú, sin heredar un ritual oral de flags.

Organizaciones: equipos, roles y permisos

Las organizaciones son la capa de gobernanza sobre los scopes. Una organización posee un scope y modela quién puede qué mediante equipos y roles:

• Propietario: control total, incluida la facturación y el borrado de la organización.
• Administrador: gestiona miembros, equipos y paquetes, sin tocar la facturación.
• Miembro: accede a los paquetes según los permisos de sus equipos.

Los permisos se asignan por paquete —lectura o escritura— a través de equipos, y la organización puede exigir doble factor a todo el que publique.

Así, el equipo de diseño escribe en @acme/ui mientras el de datos solo lo lee, y ninguna publicación ocurre sin segundo factor. El scope deja de ser un prefijo para convertirse en una frontera organizativa con política real.

flowchart TD
O[organizacion acme] --> T1[equipo diseno]
O --> T2[equipo datos]
T1 -->|escritura| P1[paquete acme ui]
T2 -->|lectura| P1
T2 -->|escritura| P2[paquete acme metrics]
style O fill:#89b4fa,color:#11111b
style P1 fill:#a6e3a1,color:#11111b
style P2 fill:#a6e3a1,color:#11111b