lpm add

lpm add <package>

lpm add extracts a package's source files into your project rather than installing it as a runtime dependency. Think shadcn-ui style: the code lands in your repo, you own it, you edit it.

lpm install is the runtime-dependency command. lpm add is the source-delivery command. The two are not aliases.

Works with any registry the resolver can reach — lpm.dev, npmjs.org, or a .npmrc-declared private registry. Anything that ships a tarball is fair game.

Examples

lpm add @lpm.dev/owner.ui-kit                      # add an lpm.dev package
lpm add @lpm.dev/owner.ui-kit@1.2.0                # add a specific version
lpm add @lpm.dev/owner.ui-kit?component=dialog     # add only one component
lpm add lodash.merge                               # add an npm package's source
lpm add @my-co/internal --path ./src/vendor        # custom destination
lpm add my-pkg --dry-run                           # preview without writing

How it works

1. Resolves the spec against the appropriate registry.
2. Downloads the tarball into a temporary file and extracts it to a tempdir. Unlike lpm install, the tarball is not persisted to ~/.lpm/store/ — lpm add is a copy-and-discard flow. Re-running lpm add re-downloads.
3. Picks where to put the files. With --path, honors it. Without --path in a TTY (and not --yes / --json), prompts for an install directory. Non-interactive (--yes, --json, or non-TTY) requires --path for simple-path packages (no lpm.config.json); config-aware packages auto-detect from their declared ecosystem.
4. Copies the source into the destination, prompting on conflicts.
5. If the package declares an lpm.config.json, runs the package's configured install steps (component selection, alias rewrites, dep installation). If not, it's a plain source copy and you handle dependencies yourself.

lpm add does not auto-install bare imports it discovers in the copied source. It will surface them at the end of the run so you can add them yourself.

Human output is structured around the source-copy flow:

› Downloading source package source-pkg@1.0.0
› Detecting project structure
    Framework:    Vite
    Install path: src/components
    Import alias: @/src/components/
✓ Files copied
+ Foo.tsx
› Installing declared dependencies
+ lucide-react@^0.400.0
✓ Done · added 1 file and 1 dependency in 486ms

File conflicts use a slim warning line (! File exists: ...) before the interactive choice.

Config-aware vs simple copy

A package becomes "config-aware" by shipping an lpm.config.json at the tarball root. That file declares components, dependencies to auto-install, import aliases, and editor integration hints. Without it, lpm add is a plain source copy — useful for any tarball, not just lpm.dev packages.

Swift packages

For Swift packages, prefer lpm install — it's the right command for SPM dependencies (resolves through the SE-0292 registry and edits Package.swift). lpm add still works for Swift sources today and respects --target for Xcode-target wiring, but consider it the legacy path for that ecosystem.

Authoring config-aware packages: lpm.config.json

Ship lpm.config.json at the root of your tarball to control how lpm add extracts your package. With the file present, lpm add becomes a configurable installer — interactive prompts, conditional file copying, conditional dependency injection, import-path rewriting.

{
  "$schema": "https://lpm.dev/schemas/lpm.config.json",
  "ecosystem": "js",
  "importAlias": "@/",
  "configSchema": {
    "component": {
      "type": "select",
      "label": "Which component?",
      "options": ["dialog", "popover"],
      "default": "dialog",
      "required": true
    },
    "withTests": { "type": "boolean", "label": "Include tests?", "default": false }
  },
  "files": [
    { "src": "src/dialog/**", "dest": "dialog", "include": "when",
      "condition": { "component": "dialog" } },
    { "src": "tests/**", "dest": "__tests__", "include": "when",
      "condition": { "withTests": true } }
  ],
  "dependencies": {
    "withTests": { "true": ["vitest"] }
  }
}

The full schema reference — every field, every value type, every default — lives at lpm.config.json. The published JSON Schema at https://lpm.dev/schemas/lpm.config.json drives editor autocomplete (add $schema as shown above).

Pre-answering prompts

Prompts can be pre-answered from the CLI by appending ?key=value&key=value to the package spec:

lpm add @lpm.dev/owner.ui-kit?component=dialog&styling=panda

Inline values bypass the prompt entirely. With --yes, prompts are skipped and defaultConfig / configSchema.<field>.default fill in any required fields the user didn't supply.

Behavior matrix

Prerequisites

If the source package declares dependencies (config-driven or via its own package.json), your project must already have a package.json. lpm add runs a preflight check before copying any files and exits early with a remediation hint if the manifest is missing — there's nowhere for the dep entries to land otherwise, and we'd rather fail loudly than copy source files you can't import from.

$ lpm add @author/ui-kit
error: this source package declares dependencies, but the project has no
       `package.json` to record them in.
       Run `lpm init` (or `npm init -y`) first to create a manifest, then
       re-run `lpm add`.
       To copy the source files without installing the declared dependencies,
       pass `--no-install-deps` and resolve the imports yourself.

If you only want the source files (and you'll handle the imports yourself), pass --no-install-deps to skip the preflight and let the copy proceed without touching package.json.

Flags

Plus the global flags.

See also

• lpm remove — undo an lpm add
• lpm install — install runtime dependencies
• Registries — how packages route
• Swift Package Registry — SE-0292 design and the lpm install-preferred path for Swift