npm package: @napled/cli
Description: CLI Tool for Napled components
Author: Zillowe Foundation
Latest version: 0.6.0

# Napled CLI

[![JSR Version](https://jsr.io/badges/@napled/cli)](https://jsr.io/pkg/@napled/cli)
[![npm Version](https://img.shields.io/npm/v/@napled/cli.svg)](https://www.npmjs.com/package/@napled/cli)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache-yellow.svg)](https://opensource.org/licenses/apache-2.0)

A smart command-line tool for scaffolding components and themes directly into your project. `napled` reads your `shadcn/ui` configuration, resolves dependencies, and installs everything you need with a single command.

Inspired by the `shadcn/ui` CLI, `napled` is designed to accelerate your development by providing a seamless bridge between your component library and your application.

---

## Features

-   **shadcn/ui Aware**: Automatically detects your project's paths from `components.json` and `tsconfig.json`.
-   **Smart Dependency Resolution**: When you add a component, `napled` automatically installs its dependencies from both the source library and `shadcn/ui`.
-   **Component Discovery**: List all available components and themes directly from your terminal with `napled list`.
-   **Custom Repositories**: Point the CLI to any GitHub, GitLab, or Gitea/Forgejo repository to use your own component libraries.
-   **Version Pinning**: Fetch components from a specific branch or tag for version consistency.
-   **Theme Management**: Easily add and manage themes by appending styles to your global CSS file.

---

## Getting Started

Using `napled` is a simple three-step process.

### Prerequisites

Your project must be set up with `shadcn/ui`. If you haven't done so, please run its initialization command first:

```bash
npx shadcn@latest init
```

### 1. Verify Your Configuration

Run the `napled init` command to customize the package manager and ensure your project is correctly configured and ready to use `napled`.

```bash
npx @napled/cli@latest init
```

If successful, you will see a confirmation message. This command doesn't create any files; it only validates your existing `shadcn/ui` setup.

### 2. List Available Components

To see what components are available to install, use the `list` command.

```bash
npx @napled/cli@latest list
```

This will fetch the component registry and display a clean list of all available component names.

### 3. Add a Component

Use the `add` command to add a component to your project. `napled` will handle the rest, including installing all necessary dependencies.

```bash
npx @napled/cli@latest add Header
```

Adds a component to your project. `napled` automatically handles all dependencies
1. Internal Dependencies: Installs other components from the source library that are required.
2. `shadcn/ui` Dependencies: Installs required base components from the official `shadcn/ui` registry.
3. npm Dependencies: Installs any required third-party npm packages (e.g. `framer-motion`) using the package manager you configured during `init`.

---

## Command Reference

### `napled init`

Verifies that the project is configured for `shadcn/ui` by checking for a valid `components.json` file and lets you customize the default package manager.

### `napled list`

Fetches and lists all available components from the configured repository's registry.

### `napled add <component-name>`

Adds a component and its dependencies to your project.

-   `<component-name>`: The name of the component to add (e.g. "Faq", "Header"). Use `napled list` to find available components.

### `napled theme <theme-name>`

Fetches a theme's CSS variables and appends them to the global CSS file defined in your `components.json`.

-   `<theme-name>`: The name of the theme to apply (e.g. "shark", "zillowe").

### `napled set repo <repo-url>`

Configures the CLI to use a custom repository for components and themes. This creates a `napled.json` file in your project's root.

**Options:**
-   `--branch <name>`: Specify a branch or tag to use (e.g. "next", "v1.2.0"). Defaults to `main`.
-   `--github`, `--gitlab`, `--gitea`, `--forgejo`: Manually specify the platform if auto-detection fails (e.g. for self-hosted instances).

**Examples:**
-   **GitHub (auto-detected):**
    ```bash
    napled set repo https://github.com/your-org/my-design-system
    ```
-   **GitLab with a specific branch:**
    ```bash
    napled set repo https://gitlab.com/your-org/my-design-system --branch next
    ```
-   **Self-Hosted Gitea Instance:**
    ```bash
    napled set repo https://git.mycompany.com/design/components --gitea
    ```

---

## How It Works (Architecture)

`napled` intelligently connects to a source repository that contains a component registry.

-   **`components/registry.json`**: This manifest file in the source repository defines each component, its source files, its internal dependencies (other components in the repo), and its external `shadcn/ui` dependencies.
-   **`napled.json`**: A local configuration file created by `set repo` that allows you to override the default source repository.
-   **`components.json` & `tsconfig.json`**: Your project's existing `shadcn/ui` and TypeScript configuration files are used to determine where to place files.

For detailed information on the internal modules and functions, please see the TSDoc comments in the source code, which are rendered on the [JSR package page](https://jsr.io/@napled/cli).

## Contributing

Contributions are welcome! If you'd like to help improve `napled`, please feel free to open an issue or submit a pull request on our [GitLab repository](https://gitlab.com/Zillowe/Zillwen/Zowdy/Napled).

## License

Licensed under the [Apache 2.0 License](https://opensource.org/licenses/apache-2-0).