BetaPublic beta — Read the release notes
Solidiom
Get Started
Documentation

Add a Primitive

solidiom add installs a primitive into your project, either as an npm package or as materialized source files.

Basic Usage

solidiom add dialog

This resolves the dependency graph for dialog and outputs the npm install command. In package mode, it prints the command without running it by default.

Package Mode vs Source Mode

Package mode (default): Resolves the capability graph and outputs the appropriate npm install, pnpm add, or yarn add command for all required packages. The CLI detects your package manager automatically.

solidiom add dialog --mode package

Source mode: Materializes source files directly into your project at the configured sourceDir. It handles import rewriting, runtime deduplication, and lockfile tracking.

solidiom add dialog --mode source

Flags

FlagDescription
--modeInstall mode: package or source
--registryCustom registry URL for package resolution
--no-networkUse only cached or local registry data
--deliverableProduct-layer deliverable: primitive, component, block, template, theme
--stylingStyling profile: css, tailwind, unocss
--package-managerOverride package manager detection (npm, pnpm, yarn, bun)
--installRun the install command instead of only printing it
--allow-unverifiedProceed with source install even if byte-level verification fails
--forceOverwrite files modified locally since last source install
--diffPrint a unified diff of pending source-install changes without writing
--dry-runShow what would be done without writing
--jsonOutput as JSON

Deliverable Kinds

The --deliverable flag requests a specific product-layer output:

  • primitive — Core primitive with its adapters and runtime
  • component — Composited component with styling, installed into componentDir
  • block — Domain-aware block with layout and state, installed into blockDir
  • template — Full project template
  • theme — Theme package, installed into themeDir

Styling Profiles

Use --styling to request a specific styling output:

  • css — CSS custom properties and utility classes
  • tailwind — Tailwind CSS utility classes
  • unocss — UnoCSS utility classes

Conflict Handling

In source mode, if locally modified files would be overwritten, the install is blocked with remediation hints:

Blocked — locally modified files would be overwritten:
  ✗ src/ui/primitives/dialog/Dialog.tsx

Options to resolve conflicts:

  1. solidiom add dialog --mode source --diff — Preview pending changes before applying
  2. solidiom add dialog --mode source --force — Overwrite locally modified files
  3. solidiom diff dialog — Review all changes between installed source and lockfile

Verification Bypass

By default, source installs require byte-level verification against the registry manifest. If verification fails, you can bypass with --allow-unverified. The lockfile records the entry with provenance: "unverified" so it can be audited later.

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

Package Manager Detection

The CLI auto-detects your package manager by looking for lock files (pnpm-lock.yaml, yarn.lock, bun.lockb) or configuration files. Override with --package-manager:

solidiom add dialog --install --package-manager pnpm

Pass --install to actually run the install command rather than just printing it.