DOCSEARCHbyAlgolia
Submit Docs

Lightswind UI Library Documentation

repository·Master·Indexed 21 days ago

https://github.com/codewithmuhilan/lightswind-ui-library

An AI-native, CLI-first React component library featuring 160+ professional and animated components, blocks, and templates. Lightswind uses a source-first architecture, delivering raw .tsx files directly into project directories for complete user ownership. It supports Node.js 18+, React 18/19, and Tailwind CSS v3/v4, and includes a native Model Context Protocol (MCP) server for integration with AI coding agents like Cursor and Claude.

Tokens
10.5K
Snippets
37
Records
51
Agent score
73%

What's inside Lightswind UI

  1. Understand Lightswind UI Source-First Architecture

    Master

    Lightswind UI follows a Source-First Architecture. Unlike traditional libraries that act as runtime dependencies, Lightswind delivers raw .tsx files directly into your project. This ensures you own the code, can customize it freely, and avoid vendor lock-in.

    Project Structure

    When initialized, your project will follow this pattern:

    Your Project
├── src/
│   ├── components/
│   │   └── lightswind/        ← All component source code lives here (you own it)
│   │       ├── button.tsx
│   │       ├── globe.tsx
│   │       └── ...
│   └── lib/
│       └── utils.ts           ← Shared utilities (cn, throttle, etc.)
├── tailwind.config.ts         ← Lightswind plugin auto-registered here
└── lightswind.config.json     ← CLI config (paths, theme, license)

    Core Principles

    1. Source over Runtime: Components are raw .tsx files, not compiled blobs.
    2. User Ownership: Components are yours to edit and extend forever.
    3. Zero Dependency Bloat: Only install dependencies for the components you actually use.
    4. Smart Automation: The CLI handles all configuration and dependency resolution.

  2. Correctly import Lightswind components

    Master

    Lightswind UI follows a "Source over Runtime" architecture. Components are delivered as raw .tsx files into your local project directory rather than being imported from a node_modules package.

    Do not attempt to import from the package name. Instead, import from the local path where the component was added (usually within your components folder).

    Incorrect: import { Button } from "lightswind"

    Correct: import { Button } from "@/components/lightswind/button" (or your specific configured path).

  3. Authenticate with Lightswind Pro

    Master

    Lightswind Pro provides access to premium components and page templates.

    CLI Authentication

    Get your license key from the Lightswind Dashboard and run:

    npx lightswind auth login sk_pro_YOUR_LICENSE_KEY

    Credentials are stored in ~/.lightswindrc.

    CI/CD Authentication

    Set the following environment variable in your CI/CD pipeline:

    LIGHTSWIND_LICENSE_KEY=sk_pro_YOUR_LICENSE_KEY

    Once authenticated, you can use premium commands like:

    npx lightswind add iphone16-pro
npx lightswind add-block saas-hero
    npx lightswind auth login sk_pro_YOUR_LICENSE_KEY

  4. Add Lightswind components and blocks via CLI

    Master

    Lightswind UI uses a CLI-first approach for component delivery. Instead of manual copy-pasting, you can programmatically add components or pre-designed blocks directly to your source code.

    • Components: Use npx lightswind add [component-name] to add a single component.
    • Blocks: Use npx lightswind add-block [block-name] to add pre-designed page sections (like Hero or Pricing sections).

    The CLI automatically manages dependencies; it scans your package.json and prompts you to install required peer dependencies (such as framer-motion, gsap, or three) during the installation process.

    npx lightswind add [component-name]
npx lightswind add-block [block-name]

  5. Quick Start: Install and use Lightswind UI

    Master

    Lightswind UI is a source-code component library where components are installed directly into your project directory rather than being a runtime dependency.

    Requirements

    • Node.js 18+
    • React 18 or 19
    • Tailwind CSS v3 or v4
    • A Next.js, Vite, Remix, or CRA project

    1. Initialize

    Run the following command from your project root to detect your framework, locate your components folder, install shared utilities, and register the Tailwind plugin:

    npx lightswind@latest init

    During setup, you will be prompted to select a color theme (e.g., default, deep-ocean, crimson, emerald, amber, amethyst, or mono).

    2. Add a Component

    Use the CLI to add specific components. The CLI automatically resolves and installs any necessary prerequisites.

    npx lightswind add globe
npx lightswind add border-beam
npx lightswind add toast

    3. Import & Use

    Important: Never import directly from the "lightswind" package. All components are installed into your local components/lightswind/ directory. Import them from your local path:

    import { Globe } from "@/components/lightswind/globe";

export default function HeroSection() {
  return (
    <section>
      <Globe />
    </section>
  );
}
    npx lightswind@latest init

  6. Integrate Lightswind UI with AI coding agents (MCP)

    Master

    Lightswind UI is the only component library with a native Model Context Protocol (MCP) server, allowing AI agents (like Cursor, Claude Desktop, or Windsurf) to interact with the library directly.

    To enable this integration, run:

    npx lightswind@latest mcp init

    Once initialized, the agent can use 8 specialized tools to list_all_components, search_components, get_component, get_block, and more, to assist in your development workflow.

  7. Integrate Lightswind with AI Agents via MCP

    Master

    Lightswind UI includes a native Model Context Protocol (MCP) server that allows AI coding assistants (Cursor, Claude, GitHub Copilot, etc.) to search, read documentation, and install components autonomously.

    Automatic Setup (Recommended)

    Run this command to auto-detect your editor and write the correct configuration:

    npx lightswind mcp init

    Manual Configuration

    If automatic setup is not used, you can manually add the server to your editor's MCP settings.

    Cursor / Windsurf

    Edit ~/.cursor/mcp.json:

    {
  "mcpServers": {
    "lightswind-mcp": {
      "command": "npx",
      "args": ["-y", "lightswind", "mcp"],
      "env": {
        "LIGHTSWIND_LICENSE_KEY": "sk_pro_YOUR_KEY"
      }
    }
  }
}

    Claude Desktop

    Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

    {
  "mcpServers": {
    "lightswind-mcp": {
      "command": "npx",
      "args": ["-y", "lightswind", "mcp"],
      "env": {
        "LIGHTSWIND_LICENSE_KEY": "sk_pro_YOUR_KEY"
      }
    }
  }
}

    VS Code (Cline / Continue)

    {
  "mcpServers": {
    "lightswind-mcp": {
      "command": "npx",
      "args": ["-y", "lightswind", "mcp"]
    }
  }
}
    npx lightswind mcp init

  8. Initialize Lightswind UI in your project

    Master

    To set up Lightswind UI, use the init command. This command acts as the project's 'brain': it detects your environment (e.g., Next.js or Vite), locates your components folder, and automatically configures the Tailwind CSS plugin. It also ensures core utilities like lib/utils and hooks are available.

    Note: Always run init before attempting to add specific components to ensure the environment is correctly configured.

    npx lightswind@latest init

  9. Authenticate for Pro components

    Master

    Pro premium components and template blocks require authentication via a license key. Use the auth login command to provide your key. Once the code is delivered to your local project, it is yours to keep and edit; there is no runtime dependency on the API key.

    npx lightswind auth login --key=LICENSE_KEY

  10. Use 3D effects with Lightswind UI

    Master

    Lightswind UI components support two visual modes: Flat and 3D.

    1. Global 3D Mode: Enable via the plugin configuration: { effect3d: true }.
    2. On-demand 3D Mode: If the plugin is configured with effect3d: false (the default), you can apply 3D styles to specific elements by adding the following classes to a parent container:
      • .lw-3d
      • .theme-3d

    These classes will scope the 3D styles to their children, even when using .dark mode.

    <!-- 3D effects enabled via wrapper when global effect3d is false -->
<div class="lw-3d">
  <button class="btn-3d-default">3D Button</button>
</div>

  11. Configure the Lightswind Tailwind plugin

    Master

    The lightswind Tailwind plugin is automatically configured during the init process. It handles the registration of component-level CSS variables, animation keyframes, dark mode tokens, and the optional 3D effect system. You must add it to your tailwind.config.ts file.

    // tailwind.config.ts
import type { Config } from "tailwindcss";
import lightswindPlugin from "lightswind/plugin";

const config: Config = {
  content: ["./src/**/*.{ts,tsx}"],
  darkMode: "class",
  plugins: [
    lightswindPlugin({
      effect3d: false,  // Set to true to enable global 3D styling mode
    }),
  ],
};

export default config;