Napled CLI

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:

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.

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.

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.

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):

  napled set repo https://github.com/your-org/my-design-system

• GitLab with a specific branch:

  napled set repo https://gitlab.com/your-org/my-design-system --branch next

• Self-Hosted Gitea Instance:

  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.

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.

License

Licensed under the Apache 2.0 License.