Actualizar a Boltdocs 3.2.0

3.2.0 es semver-minor documentado, pero toca tu node_modules al instalar en tres lugares. Esta página es la auditoría + las recetas que te llevan más allá de los install warnings limpiamente. Si solo necesitás el titular: leé el blog post del release 3.2.0, y volvé si tu pnpm install se queja.

1. La auditoría de un vistazo

Un nuevo test fija este contrato: packages/core/tests/package-shape.test.ts. Cualquier PR futuro que accidentalmente re-infle el surface area rompe el CI.

2. Recetas de migración

2a. El paste mínimo (95% de los usuarios)

// package.json
{
  "dependencies": {
    // ...existentes...
    "boltdocs": "^3.2.0",
    // ↓ Agregá esta línea — antes era transitivo:
    "react-aria-components": "^1.16.0"
  }
}

pnpm install

Sin cambios de código. Sin cambios de configuración. El peer warning se limpia.

2b. Si usás @bdocs/plugin-image-optimizer

El optimizer ya declara sharp y svgo como peerDependenciesMeta.optional — el comportamiento de install queda igual. Las peerDependencies del optimizer los proveen cuando el usuario opta in. Si no lo tenés:

pnpm add @bdocs/ssg \
  @bdocs/plugin-image-optimizer \
  sharp@^0.34.5 \
  svgo@^4.0.1

Los sitios que no usan el image optimizer obtienen un node_modules más chico — sharp y svgo simplemente están ausentes del árbol.

2c. Si sos autor de un plugin que importaba iconos internos

El import path viejo '../icons-dev' ya no existe. Reemplazalo con el path nuevo apropiado:

// ❌ Antes de 3.2.0 — gone
import { Github, Cs } from '../icons-dev'

// ✅ Después de 3.2.0 — íconos prod/nav
import { Github } from 'boltdocs/client/icons-prod'    // (planeado; path actual: 'boltdocs/client')

// ✅ Después de 3.2.0 — íconos de lenguajes eliminados
// `lang-icons.tsx` ya no existe en la API pública. Renderizá tu propio
// ícono junto al título a través del valor `effectiveTitle` del hook
// `useCodeBlock`, o simplemente mostrá el texto del título sin ícono.

Para los iconos sociales, usá los exports nuevos de icons-prod.tsx.

2d. Lockfiles versionados

Si tu repo usa pnpm-lock.yaml desde 3.1.x, corré pnpm install una vez después de bumpear boltdocs a ^3.2.0. El lockfile reescribirá las entries para react-aria-components (ya no es transitivo). Esperá quejas de pnpm install --frozen-lockfile solo en la primera corrida — eso es esperado, la reescritura es necesaria una sola vez.

Si no podés reescribir el lockfile (frozen por seguridad), pineá react-aria-components a una versión que tu tooling ya aprueba, después agregá la receta de .npmrc de §3 más abajo.

3. Setups de CI / lockfile estrictos

Tres entornos golpean el peer warning fuerte:

1. Husky + lint-staged pre-commit con pnpm install --frozen-lockfile --strict-peer-dependencies.
2. Renovate / Dependabot con políticas marcadas ignoreUnstable: false que flaggean missingPeer como rojo.
3. Turborepo / Nx monorepos que envuelven el build del consumidor en pnpm install --strict-peer-dependencies.

Para los tres, la fix es una línea en .npmrc que hoistea react-aria-components al scope de tu lockfile explícitamente, sin desactivar globalmente los peer checks:

# .npmrc
# Permití el peer advisory documentado de boltdocs@3.2 → react-aria-components.
# Esto NO es un disable global — solo este peer específico está whitelisteado.
public-hoist-pattern[]=*react-aria-components*

Forma equivalente en .pnpmrc (sintaxis pnpm-nativa — sin corchetes):

# .pnpmrc
# Hacés que react-aria-components sea un peer explícito y transparente en el lockfile.
# `.pnpmrc` NO usa la sintaxis `[]` de array — la forma pnpm-nativa es sin corchetes por línea.
public-hoist-pattern=*react-aria-components*
peerDependencyRules.allowedVersions.react-aria-components=^1.16.0

No uses legacy-peer-deps=true o auto-install-peers=false. Ambos silencian cada peer warning en todo el árbol y van a enmascarar futuras roturas reales. Las dos configs de arriba están scoped al único peer advisory específico que documenta 3.2.0.

Pre-flight check

Después de agregar la regla en .npmrc, verificá que el install ahora se vea así:

pnpm install --frozen-lockfile
# → Sin peer warnings
# → boltdocs@3.2.0 install OK
# → react-aria-components visible al tope del dep tree, no nestado

Si todavía ves el warning, corré pnpm why react-aria-components — el output debería mostrar dos owners: boltdocs (peer) y tus propias deps (tu línea de react-aria-components). Eso confirma que el hoist pattern funcionó.

4. Comportamiento runtime — qué no cambió

Para los usuarios que se saltean el snippet de migración, el runtime es idéntico a 3.1.x. Específicamente:

• Los imports no cambiaron. Todos los exports públicos desde 'boltdocs', 'boltdocs/client', 'boltdocs/server', 'boltdocs/primitives', 'boltdocs/mdx' resuelven a los mismos símbolos que 3.1.x.
• Los componentes DocsLayout, Navbar, Sidebar, OnThisPage, SearchDialog, Breadcrumbs, PageNav funcionan igual. Los íconos que renderizan se ven idénticos.
• Los code blocks MDX renderizan solo el título. Los títulos de los code blocks muestran el texto del nombre del archivo sin ningún icono de lenguaje — se renderiza un icono de archivo genérico de forma incondicional para balance visual. Este es un cambio visual respecto a 3.1.x.
• fetch a los endpoints de API feedback / GitHub discussions / Giscus funcionan igual. Sin cambios de transporte.
• Las integraciones de plugins Vite, @bdocs/plugin-mermaid, @bdocs/plugin-math, @bdocs/plugin-rss, @bdocs/plugin-ask-ai siguen sin cambios — mantienen sus propios dep trees.

No hay flash en tiempo de hidratación: el ícono File genérico es lo único que se renderiza, y viaja con la página en el primer paint.

5. FAQ

"¿Tengo que instalar react-aria-components explícitamente?"

Sí, pero solo si tu proyecto todavía no tiene un transitivo. Si ya tenés react-aria-components en tu lockfile desde otro paquete (raro para un install de 3.1.x — boltdocs era el único transitivo común), el peer warning queda en silencio.

Si tu shell de framework — por ejemplo un template de CMS, un stack derivado de shadcn, o un design system interno — ya declara react-aria-components como dep, ya estás cubierto.

"¿Por qué no hicieron react-aria-components un peer optional?"

Porque react-aria-components es directamente importado por 8 primitivos del cliente (Button, Sidebar, SearchDialog, Tooltip, Popover, Menu, Navbar, Breadcrumbs, ThemeToggle). Marcarlo como optional dejaría que los sitios se salten el install y crasheen silenciosamente en cada página con un navbar.

La ubicación como peer hard matchea el comportamiento binario: 3.2.0 requiere react-aria-components en runtime exactamente como lo hacía 3.1.x. El peer simplemente surfaccea ese requerimiento al install tool en lugar de enterrarlo.

"¿Fallará mi CI con el install warning?"

Solo si tu CI corre pnpm install --strict-peer-dependencies o lee la salida de npm warn y trata warnings como errores. Agregá la regla de .npmrc de §3 para whitelisteear este peer advisory específico sin desactivar los peer checks globalmente.

"¿Por qué no hicieron sharp / svgo peers de boltdocs en lugar de moverlos fuera?"

Dos razones:

1. La mayoría de los sitios no los necesitan. Un framework de docs no debería arrastrar un binario nativo de 35 MB al install de un sitio que nunca optó por image optimization. Moverlos al optional-peer meta del image optimizer hace que esa elección sea explícita.
2. sharp es ampliamente conocido como un dep hostil al install en Alpine ARM, musl libc y glibc viejo. Removerlo de boltdocs significa que boltdocs ahora instala limpiamente en esas plataformas sin importar si el usuario usa image optimization o no.

"¿Hay alguna forma de mantener sharp y svgo en mi árbol sin el image optimizer?"

Sí — instalalos explícitamente:

pnpm add sharp svgo

Vuelven a tu árbol (si realmente los querés), sin que boltdocs los declare.

"¿Sigue siendo @bdocs/ssg independiente?"

Sí. @bdocs/ssg es un paquete separado del workspace y tiene sus propios peerDependencies (react, react-dom, react-router-dom). No queda afectado por la reconfiguración de peers de boltdocs 3.2.0.

"¿Va a crecer el tamaño de mi bundle boltdocs/client después del upgrade?"

No. De hecho, en páginas con code blocks MDX, el bundle baja ~17 KB (el módulo completo lang-icons.tsx fue eliminado del core). Las páginas sin code blocks ya estaban en cero bytes para estos íconos desde el lazy-load de 3.2.0. Consultá la sección de peso del paquete en el blog para la tabla completa de antes/después.

6. Plan de rollback

Si necesitás volver a 3.1.x post-upgrade:

pnpm add boltdocs@3.1.x

El lockfile revierte sin ediciones manuales porque 3.1.x y 3.2.0 comparten la misma superficie pública. Revertí la declaración explícita de react-aria-components solo si tu build se queja (la mayoría no).

Ver también

• Blog post del release 3.2.0 — el porqué detrás de estas decisiones
• Guía de instalación — flujo de install nuevo
• Guía de autoría de plugins — para autores de plugins afectados por el split de iconos
• Referencia de configuración — schema completo de configuración