@levi-putna/element

Install UI elements from a git repo into your project: copy-in source (like shadcn/ui), resolve element and npm dependencies, and keep install metadata beside each component.

npx @levi-putna/element@latest add levi-putna/elements

Works with catalogs that use a .element manifest or a shadcn-compatible registry.json (for example levi-putna/elements).

Quick start

# Browse a catalog
npx @levi-putna/element@latest list levi-putna/elements

# Interactive install (pick element + path, confirm plan)
npx @levi-putna/element@latest add levi-putna/elements

# Named element + path
npx @levi-putna/element@latest add levi-putna/elements --element button --path components/ui

# Skip all prompts (including overwrites)
npx @levi-putna/element@latest add levi-putna/elements --element scheme -y

Also accepts full GitHub URLs and branches:

npx @levi-putna/element@latest add https://github.com/levi-putna/elements
npx @levi-putna/element@latest add levi-putna/elements@develop --element badge

Optional: set GITHUB_TOKEN if you hit API rate limits or need private repos.

Commands

| Command | Description | |---------|-------------| | init | Create .element/config.json | | add <owner/repo> | Install elements (and their element deps) | | list <owner/repo> | List remote elements | | installed | Show lockfile + detected install paths | | update [name] | Re-fetch from lockfile sources | | remove <name> | Remove files, sidecar, and lock entry | | publish | Maintainer release (version + GitHub + npm) |

Flags for add

| Flag | Short | Behaviour | |------|-------|-----------| | --element <name> | -e | Install a specific element (skip picker) | | --path <dir> | -p | Install directory override | | --yes | -y | Skip all prompts; overwrite conflicts; pick default path | | --overwrite | -o | Overwrite existing files (still confirms plan unless -y) | | --silent | -s | Quiet spinners and logs | | --cwd <dir> | | Project root (default: current directory) |

Flags for publish

| Flag | Behaviour | |------|-----------| | --patch / --minor / --major | Semver bump (required with -y) | | --yes / -y | Skip confirmation prompts | | --dry-run | Preview; npm publish --dry-run; no real push/publish | | --no-push | Skip git push | | --no-npm | Skip npm publish | | --no-notes | Skip CHANGELOG.md and GitHub release notes | | --no-github-release | Write CHANGELOG.md but skip gh release create |

How install works

1. Fetch the catalog (registry/ or elements/) from GitHub.
2. Resolve the selected element and its elementDependencies / registryDependencies.
3. Detect install paths from .element/config.json and existing *.element.json sidecars (for example ui/elements and ui/components).
4. Show a plan: elements (requested vs dependency), files (+ create / ~ overwrite / = skip), and npm packages.
5. On confirm: install missing npm packages, write files, write sidecars, update .element/lock.json.

Package manager is detected from lockfiles / packageManager (prefers yarn when ambiguous).

Project store: .element/

Created by init or on first add:

.element/
  config.json    # known paths, defaultPath, packageManager
  lock.json      # installed elements → source provenance

config.json

{
  "paths": {
    "components/ui": 3,
    "ui/elements": 1
  },
  "defaultPath": "components/ui",
  "packageManager": "yarn"
}

lock.json

{
  "elements": {
    "button": {
      "repo": "levi-putna/elements",
      "branch": "main",
      "catalogRoot": "registry",
      "installPath": "components/ui",
      "files": ["button.tsx"],
      "installedAt": "2026-08-12T00:00:00.000Z"
    }
  }
}

Installed sidecar: <name>.element.json

Written next to the installed files (for example components/ui/button.element.json):

{
  "name": "button",
  "source": {
    "repo": "levi-putna/elements",
    "branch": "main",
    "catalogRoot": "registry",
    "path": "registry/button"
  },
  "installedAt": "2026-08-12T00:00:00.000Z",
  "dependencies": ["@base-ui/react", "class-variance-authority", "lucide-react"],
  "devDependencies": [],
  "elementDependencies": ["utils"],
  "files": ["button.tsx"],
  "description": "…"
}

These sidecars are how the CLI discovers which directories you already use for elements.

If you install into a dedicated folder per element, a bare .element file inside that folder is also recognised when scanning.

Source manifests (publishers)

Put each element in registry/<name>/ or elements/<name>/.

Preferred: .element

{
  "name": "scheme",
  "type": "ui",
  "description": "Strata scheme identity primitives.",
  "dependencies": ["lucide-react"],
  "devDependencies": [],
  "elementDependencies": ["utils", "badge"],
  "files": [
    { "path": "scheme.tsx", "target": "scheme.tsx" }
  ],
  "category": "ui"
}

Compatible: shadcn registry.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "type": "registry:ui",
  "description": "…",
  "dependencies": ["lucide-react"],
  "registryDependencies": ["utils"],
  "files": [
    {
      "path": "registry/button/button.tsx",
      "target": "components/ui/button.tsx",
      "type": "registry:ui"
    }
  ]
}

The CLI uses the filename from target and installs into the path you choose (or detect). Prefer .element for new catalogs; existing shadcn registries work without changes.

Path detection

1. --path if provided.
2. Else .element/config.json paths / defaultPath.
3. Else scan for *.element.json / .element and group by parent directory.
4. Interactive: present every detected path (plus “custom”).
5. With -y: use defaultPath, else the most-used discovered path, else components/ui.

Overwrites

• The install plan marks differing existing files as ~ overwrite and warns before confirm.
• -y skips prompts and overwrites.
• -o overwrites without per-file asks but still shows the plan confirm unless -y.
• Identical content is skipped (=).

Maintainer release

Use the package-publish-element skill and/or CLI. Releases generate notes from commits since the last tag, prepend them to CHANGELOG.md, create a GitHub Release (via gh when available), then version / push / publish:

# Preview (includes release notes)
node bin/cli.js publish --dry-run --patch

# Release
node bin/cli.js publish --patch -y

Agent skill: .skills/package-publish-element/SKILL.md (linked via npx dot-skills link)

Checklist:

1. Clean working tree, tests green, npm login (optional: gh auth login)
2. Choose patch / minor / major
3. Review generated release notes
4. Version bump + CHANGELOG.md → git push --follow-tags → GitHub Release → npm publish
5. Verify with npm view @levi-putna/element version and gh release view v<version>

Local development

git clone https://github.com/levi-putna/element.git
cd element
yarn install   # or npm install
npm test
node bin/cli.js --help
node bin/cli.js list levi-putna/elements

Licence

MIT