Agregar un primitivo

El comando solidiom add es la principal forma de incorporar primitivos de Solidiom en tu proyecto. Resuelve el grafo de dependencias, aplica restricciones de política, y ejecuta la instalación en el modo seleccionado.

#Modo paquete

Por defecto, solidiom add opera en modo package. Resuelve las dependencias del primitivo y genera el comando de instalación del gestor de paquetes (npm install, pnpm add, o yarn add):

solidiom add dialog
# pnpm add @solidiom/[email protected] @solidiom/[email protected]

Para ejecutar automáticamente la instalación:

solidiom add dialog --install

La CLI detecta automáticamente el gestor de paquetes buscando archivos de bloqueo (pnpm-lock.yaml, yarn.lock, bun.lockb) o archivos de configuración. Puedes forzar un gestor de paquetes específico:

solidiom add dialog --install --package-manager yarn

#Modo código fuente

En modo source, la CLI materializa los archivos fuente del primitivo directamente en el proyecto, en lugar de instalarlos como paquetes npm:

solidiom add dialog --mode source
# Installed 3 source files
#   src/ui/primitives/dialog/Dialog.tsx
#   src/ui/primitives/dialog/index.tsx
#   src/ui/_runtime/hooks.ts

Los archivos se colocan según la configuración en .solidiom/config.json:

• sourceDir: directorio para los archivos del primitivo
• runtimeDir: directorio para el código compartido de runtime
• componentDir: directorio para entregables “component”
• blockDir: directory para entregables “block”
• themeDir: directorio para entregables “theme”

El modo de instalación también se puede definir globalmente en config.json mediante defaultMode.

#Entregables del nivel de producto

Algunos primitivos ofrecen múltiples niveles de entregable (componente, bloque, template, theme). Usa --deliverable para seleccionar uno específico:

solidiom add button --deliverable component
solidiom add dialog --deliverable block

#Perfiles de estilo

Si el primitivo soporta múltiples perfiles de estilo, puedes seleccionar uno con --styling:

solidiom add button --styling tailwind
solidiom add button --styling css
solidiom add button --styling unocss

#Ejecución simulada

La bandera --dry-run muestra lo que se haría sin escribir archivos:

solidiom add dialog --mode source --dry-run

#Verificación de código fuente

Por defecto, las instalaciones de código fuente requieren verificación a nivel de byte contra el manifiesto del registro. Si la verificación falla, puedes proceder de forma explícita:

solidiom add dialog --mode source --allow-unverified

Cuando se usa --allow-unverified, la procedencia se registra como provenance: "unverified" en .solidiom/lock.json.

#Conflictos de archivos locales

Si un archivo instalado previamente fue modificado localmente, una nueva instalación se bloquea para evitar sobrescribir cambios:

solidiom add button --deliverable component
# Blocked - locally modified files would be overwritten:
#   src/ui/components/Button.tsx

Opciones para manejar el conflicto:

1. solidiom add dialog --mode source --diff — Muestra un diff unificado de los cambios pendientes
2. solidiom add dialog --mode source --force — Sobrescribe los archivos modificados localmente

solidiom add button --deliverable component --force
solidiom add button --deliverable component --diff

#Registro personalizado y modo sin conexión

Para entornos sin acceso a Internet o con un registro privado:

solidiom add dialog --registry http://localhost:4873 --no-network

La bandera --no-network asegura que la CLI no intente solicitudes de red externas. Toda la resolución ocurre contra el catálogo local del registro.

#Bloqueo por política

Si la política .solidiom/policy.json restringe las versiones de los primitivos, y el plan resuelve una versión no permitida, la instalación se bloquea:

solidiom add dialog
# Blocked by policy violations:
#   @solidiom/[email protected] not allowed by policy (requires ^0.0.1)

#Salida JSON

solidiom add dialog --json

#Opciones