### Initialize Alpine.js with Collapse Plugin Source: https://github.com/zhengyishen0/basis-ui/blob/main/registry/ui/README.md Shows the necessary setup for Alpine.js in an Astro layout file, including importing the library and the collapse plugin, then starting Alpine. This is crucial for the reactivity and features of the Pine UI components like the Accordion. ```astro --- // Layout.astro --- ``` -------------------------------- ### Alpine.js Store Integration Example (JavaScript) Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md This JavaScript snippet shows an example of an Alpine.js store integration. Component stores are copied with components and users can modify their behavior. This specific example defines a `tableStore` with state and methods relevant to data tables. ```javascript // Component stores are copied with components // Users can modify store behavior as needed export const tableStore = { // State and methods specific to data tables }; ``` -------------------------------- ### Basis UI CLI Init Command Logic (TypeScript) Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md Outlines the steps performed by the 'init' command in the Basis UI CLI. This process includes project validation, installation of Alpine.js and plugins, Tailwind CSS setup, and configuration file creation for the component library. ```typescript // packages/cli/src/commands/init.ts // 1. Validates Astro project // 2. Installs Alpine.js + plugins // 3. Sets up Tailwind CSS with theme variables // 4. Creates components.json config // 5. Adds utility functions (cn, component variants) ``` -------------------------------- ### Install and Add Basis UI Components (Bash) Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md This snippet shows how to initialize a new Astro project with Basis UI and add specific components. It requires Node.js and npm/npx to be installed. ```bash # Initialize your Astro project npx @basisui/ui@latest init # Add components npx @basisui/ui add button card accordion ``` -------------------------------- ### Initialize Astro Project with Alpine.js CLI Source: https://context7.com/zhengyishen0/basis-ui/llms.txt Initializes a new Astro project with Alpine.js, Tailwind CSS, utility functions, and component configuration. It validates the Astro project, installs necessary Alpine.js and Astro integrations, sets up Tailwind CSS, configures tsconfig.json and tailwind.config.js, creates a global CSS file, and installs utility dependencies. This command also generates a components.json configuration file and a src/lib/utils.ts file with a cn() function. ```bash npx @basisui/ui init # Initialize with defaults (skip prompts) npx @basisui/ui init --yes # Initialize in specific directory npx @basisui/ui init --cwd /path/to/project ``` -------------------------------- ### Add Basis UI Component Library CLI Source: https://context7.com/zhengyishen0/basis-ui/llms.txt Downloads and installs the entire Basis UI component library (59 components) into your project. It checks for existing components.json, fetches the registry from GitHub, installs NPM dependencies, downloads library utilities, and extracts the UI component folder to the specified destination. This command allows for overwriting existing components and specifying custom paths or working directories. ```bash # Install complete library with prompts npx @basisui/ui add # Install with defaults (skip prompts) npx @basisui/ui add --yes # Overwrite existing components npx @basisui/ui add --overwrite # Custom component path npx @basisui/ui add --path ./src/components/custom-ui # Custom working directory npx @basisui/ui add --cwd /path/to/project ``` -------------------------------- ### Initialize Basis UI Project Source: https://github.com/zhengyishen0/basis-ui/blob/main/packages/cli/README.md Initializes your Astro project with Basis UI components. This command installs Alpine.js, sets up Tailwind CSS, creates a configuration file, and adds utility functions. ```bash npx @basisui/ui@latest init ``` -------------------------------- ### Basis UI CLI Installation Commands Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md Demonstrates the core commands for interacting with the Basis UI CLI, including project initialization, component addition, and update checking. These commands facilitate the integration and management of UI components within an Astro project. ```bash npx @basisui/ui@latest init # Setup project npx @basisui/ui add button card # Add components npx @basisui/ui diff # Check updates ``` -------------------------------- ### Select Component Example in Astro Source: https://github.com/zhengyishen0/basis-ui/blob/main/registry/ui/README.md Demonstrates how to use the Select component for dropdown selection with search functionality. It takes an array of options and a placeholder string as input. ```astro

<Checkbox
    name="terms"
    x-model="agreed"
  >
    I agree to the terms and conditions
  </Checkbox>

<Button
    type="submit"
    x-bind:disabled="!agreed"
  >
    Submit
  </Button>
</form>
```

--------------------------------

### Component Variants and Sizes with CVA in Astro

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Illustrates the use of Component Variant Authority (CVA) to manage different visual variants and sizes for the Button component in Astro. Examples include 'default', 'secondary', 'destructive', 'outline', 'ghost' variants and 'sm', 'md', 'lg' sizes, along with applying CSS transitions for effects.

```astro
---
import Button from '@/components/ui/forms/Button.astro';
---

<Button variant="default">Default</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

<Button variant="default" size="lg" class="hover:scale-105 transition">
  Hover Effect
</Button>
```

--------------------------------

### Basis UI Component Usage with Alpine.js (Astro)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md

Integrates Basis UI components with Alpine.js within an Astro template. This example demonstrates using Alpine.js directives like `x-data`, `x-on:click`, `x-bind:disabled`, and `x-show` with a Basis UI Button component for interactive behavior.

```astro
---
import Button from '@/components/ui/button/Button.astro';
---

<div x-data="{ loading: false }">
  <Button 
    x-on:click="loading = true"
    x-bind:disabled="loading"
    variant="default"
  >
    <span x-show="!loading">Submit</span>
    <span x-show="loading">Loading...</span>
  </Button>
</div>
```

--------------------------------

### Initialize Project with Basis UI CLI (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md

This command is used in a separate test project to initialize it with the Basis UI CLI after the CLI has been locally linked. It allows for testing the CLI's functionality in a real-world scenario.

```bash
npx basis-ui init
```

--------------------------------

### Initialize Project with CLI (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Initializes a new project using the locally linked Basis UI CLI. This command is run in a separate test project directory.

```bash
npx basis-ui init  # In test project
```

--------------------------------

### Run Sync and Build Registry (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Combines the 'sync' and 'build-registry' operations into a single command for convenience. This is a common step in the component update workflow.

```bash
npm run sync-all
```

--------------------------------

### Link CLI Locally for Testing (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md

After building the CLI, this command links it globally on your system, allowing you to test it in other projects without publishing. You then run 'npm link' within the 'packages/cli' directory and 'npx basis-ui init' in a test project.

```bash
npm link
```

--------------------------------

### Initialize Basis UI Project (CLI)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md

Initializes a new Astro project with Alpine.js, Tailwind CSS, and utility functions provided by Basis UI. This command sets up the foundational structure for using Basis UI components.

```bash
npx @basisui/ui init
```

--------------------------------

### Build CLI for Testing (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Builds the command-line interface (CLI) package, typically located in the 'packages/cli' directory. This is a preparatory step for local testing of the CLI.

```bash
cd packages/cli && npm run build
```

--------------------------------

### Sync UI Components to Registry

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Describes the process of synchronizing UI components from the 'basis-stack' repository to the 'basis-ui' repository using a custom npm script. This step ensures that the latest component code is copied and ready for registry building.

```bash
cd /path/to/basis-ui

# Sync components from basis-stack
BASIS_STACK_PATH=../basis-stack npm run sync

# Output:
# 🔄 Syncing entire ui/ folder from basis-stack...
# 🗑️  Removed existing ui/ folder
# ✅ Copied entire ui/ folder from basis-stack
# ✅ Copied lib files
```

--------------------------------

### Sync Components from Basis-Stack (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

This command syncs components from the basis-stack repository to the current project. It requires the BASIS_STACK_PATH environment variable to be set. This is a core part of the update workflow for components.

```bash
BASIS_STACK_PATH=../basis-stack npm run sync
```

--------------------------------

### Build Registry Metadata (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Builds the registry metadata, which is essential for discovering and managing components. This command is typically run after syncing components to ensure the registry is up-to-date.

```bash
npm run build-registry
```

--------------------------------

### Basis UI Configuration File

Source: https://github.com/zhengyishen0/basis-ui/blob/main/packages/cli/README.md

The `components.json` file in your project root defines the configuration for Basis UI, including styling preferences, Tailwind CSS integration details, and component aliases.

```json
{
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.mjs",
    "css": "src/styles/globals.css"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

```

--------------------------------

### Link CLI Locally for Testing (Bash)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Links the locally built CLI package globally, allowing it to be tested in other projects using 'npx'. This is part of the local CLI development and testing process.

```bash
npm link  # In packages/cli
```

--------------------------------

### Base Dependencies for Components (JSON)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md

This JSON array lists the base dependencies required for all components in the Basis UI library. These are essential packages that provide core functionality for styling and utility, such as class variance authority, clsx for class manipulation, and tailwind-merge for Tailwind CSS class merging.

```json
["class-variance-authority@^0.7.1", "clsx@^2.1.1", "tailwind-merge@^3.3.1"]

```

--------------------------------

### Publish Registry Updates to GitHub

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Outlines the final step in publishing UI updates: committing the updated registry files to the main branch and pushing them to the origin repository. This action makes the component updates instantly available to users without requiring a separate CLI republish.

```bash
git add registry/
git commit -m "Update button component with new variants"
git push origin main

# Components are now instantly available to all users
# No CLI republishing needed
```

--------------------------------

### Import and Use Components in Astro

Source: https://github.com/zhengyishen0/basis-ui/blob/main/registry/ui/README.md

Demonstrates how to import and use Pine UI components within an Astro application. This requires specifying the component path and then utilizing them as custom HTML elements with their respective props.

```astro
---
import { Button, Modal, Alert } from '../components/pine';
---

<Button variant="solid" color="blue" size="lg">
  Click me!
</Button>

<Alert variant="soft-green" title="Success">
  Your changes have been saved.
</Alert>
```

--------------------------------

### Sync Components Script Logic (JavaScript)

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

This script copies UI components from a source repository (basis-stack) into the registry folder. It first validates the source path, removes any existing files in 'registry/ui/', and then copies the 'src/components/ui/' and 'src/lib/' directories. This process ensures the registry contains the latest component code. The script can be run via npm scripts or directly with Node.js.

```javascript
// 1. Validates source path exists
// 2. Removes existing registry/ui/ folder
// 3. Copies entire src/components/ui/ folder from basis-stack
// 4. Copies src/lib/ files to registry/lib/
// 5. Preserves all file structure and subdirectories

```

--------------------------------

### Build Registry Script Logic (JavaScript)

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

This script scans the 'ui/' folder for component files (.astro, .js, .ts), extracts external dependencies from import statements, and generates the 'registry/index.json' file. It consolidates discovered dependencies, file counts, update timestamps, and metadata about scanned imports. The script relies on Node.js.

```javascript
// Scans all .astro, .js, .ts files in registry/ui/
// Extracts import statements:
//   - from 'alpinejs' → adds alpinejs@^3.14.9
//   - from 'class-variance-authority' → adds class-variance-authority@^0.7.1
//   - from 'astro-icon/components' → adds astro-icon@^1.1.5
// Generates registry/index.json with:
//   - All discovered dependencies
//   - File count (150 files)
//   - Last updated timestamp
//   - Metadata about scanned imports

```

--------------------------------

### Publish Basis UI CLI Updates

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Instructions for updating and publishing changes to the Basis UI CLI. This involves updating the version in `package.json`, building the CLI, testing it locally, and then publishing it to NPM.

```bash
cd packages/cli

# Update version in package.json
vim package.json  # Bump version: 0.2.2 → 0.2.3

# Build CLI
npm run build

# Test locally
npm link
npx basisui init --help

# Publish to NPM
npm publish
```

--------------------------------

### Basis UI GitHub Registry Structure (JSON)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Illustrates the JSON structure of the Basis UI component registry hosted on GitHub. This metadata includes component details, dependencies, file paths, and version information, enabling the CLI to fetch and manage components effectively.

```json
{
  "version": "1.0.0",
  "components": {
    "button": {
      "name": "button",
      "category": "forms",
      "description": "Versatile button with variants",
      "dependencies": ["class-variance-authority", "clsx"],
      "registryDependencies": ["utils", "component-variants"],
      "files": [{"path": "components/button/Button.astro"}]
    }
  },
  "lib": {
    "utils": {"files": [{"path": "lib/utils.ts"}]}
  }
}
```

--------------------------------

### Check for Basis UI Component Updates CLI

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Compares local Basis UI components with the remote registry to identify available updates. It verifies the existence of components.json, fetches the remote registry, and compares the modification time of local components with the registry's lastUpdated timestamp. This command can check all components or specific ones and can be executed within a specific directory.

```bash
# Check all components for updates
npx @basisui/ui diff

# Check specific component
npx @basisui/ui diff button

# Check in specific directory
npx @basisui/ui diff --cwd /path/to/project
```

--------------------------------

### Basis UI Configuration File (JSON)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md

The `components.json` file in your project root configures Basis UI settings, including styling options, Tailwind CSS paths, and component/utility aliases for easier imports.

--------------------------------

### Add Basis UI Components to Project

Source: https://github.com/zhengyishen0/basis-ui/blob/main/packages/cli/README.md

Adds individual or multiple Basis UI components to your Astro project. You can specify components by name and manage overwrites or paths via CLI options.

```bash
# Add individual components
npx @basisui/ui add button card

# Add multiple components
npx @basisui/ui add accordion dialog table

```

--------------------------------

### Base Dependencies for Components (JSON)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Lists the base npm dependencies required by all components in the Basis UI project. These include utility libraries like 'class-variance-authority', 'clsx', and 'tailwind-merge'.

```json
["class-variance-authority@^0.7.1", "clsx@^2.1.1", "tailwind-merge@^3.3.1"]
```

--------------------------------

### Customizing Button Component in Astro

Source: https://github.com/zhengyishen0/basis-ui/blob/main/registry/ui/README.md

Illustrates how to apply custom styling to the Button component using the `class` prop. This allows for easy integration with custom CSS or utility classes.

```astro
<Button class="my-custom-class" variant="solid">
  Custom Button
</Button>
```

--------------------------------

### Basis UI CLI Diff Command Logic (TypeScript)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

Explains the process of the 'diff' command in the Basis UI CLI. This command compares local component versions against those in the remote registry, identifies available updates, and provides recommendations for updating components.

```typescript
// packages/cli/src/commands/diff.ts
// 1. Compares local vs remote component versions
// 2. Shows available updates
// 3. Provides update recommendations
```

--------------------------------

### Create New Component with Astro and CVA

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Steps to create a new UI component within a Basis UI project using Astro. This involves creating the component file, implementing it with CVA for variants and styling, and then syncing and publishing the changes.

```bash
cd /path/to/basis-stack

# Create component file
mkdir -p src/components/ui/forms/switch
touch src/components/ui/forms/switch/Switch.astro
```

```astro
---
// src/components/ui/forms/switch/Switch.astro
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const switchVariants = cva(
  'inline-flex items-center cursor-pointer',
  {
    variants: {
      size: {
        sm: 'h-4 w-7',
        md: 'h-5 w-9',
        lg: 'h-6 w-11',
      },
      disabled: {
        true: 'opacity-50 cursor-not-allowed',
        false: '',
      },
    },
    defaultVariants: {
      size: 'md',
      disabled: false,
    },
  }
);

type Props = VariantProps<typeof switchVariants> & {
  checked?: boolean;
  name?: string;
  'x-model'?: string;
};

const { size, disabled, checked = false, name, ...alpineProps } = Astro.props;
---

<label class={cn(switchVariants({ size, disabled }))}>
  <input
    type="checkbox"
    class="sr-only peer"
    {name}
    {checked}
    {disabled}
    {...alpineProps}
  />
  <div class="relative bg-gray-200 peer-focus:ring-2 peer-focus:ring-primary rounded-full peer-checked:after:translate-x-full peer-checked:bg-primary after:content-[''] after:absolute after:top-0.5 after:left-[2px] after:bg-white after:rounded-full after:h-4 after:w-4 after:transition-all">
  </div>
</label>
```

```bash
cd /path/to/basis-ui

# Sync from source
npm run sync-all

# Commit and push
git add registry/
git commit -m "Add Switch component to forms category"
git push origin main
```

--------------------------------

### Use Basis UI Components in Astro Page (Astro)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md

Demonstrates how to import and use Basis UI components like Card and Button within an Astro page. This requires a component to be added using the CLI first. The output is an HTML structure with the integrated components.

```astro
---
import Button from '@/components/ui/button/Button.astro';
import Card from '@/components/ui/card/Card.astro';
---

<Card>
  <h2>Welcome to Basis UI</h2>
  <p>Beautiful components for your Astro project.</p>
  <Button variant="default">Get Started</Button>
</Card>
```

--------------------------------

### Add Basis UI Components (CLI)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/README.md

Adds specified Basis UI components to your Astro project. You can add single components, multiple components at once, or use options like --overwrite and --yes for unattended additions.

```bash
# Add single component
npx @basisui/ui add button

# Add multiple components
npx @basisui/ui add card dialog table

# Add with options
npx @basisui/ui add button --overwrite --yes
```

--------------------------------

### Update Basis UI Components CLI

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Command to update UI components in a Basis UI project. It uses the `@basisui/ui` package to add or overwrite existing UI components.

```bash
npx @basisui/ui add ui --overwrite
npx @basisui/ui add --overwrite
```

--------------------------------

### Alpine.js Plugin Dependencies by Component (JSON)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md

This JSON object outlines the Alpine.js plugin dependencies for specific components. Each key represents a component (e.g., 'data-table', 'accordion'), and its value is an array of the required Alpine.js plugins for that component. This allows for granular inclusion of Alpine.js features.

```json
{
  "data-table": ["@alpinejs/sort", "@alpinejs/persist"],
  "accordion": ["@alpinejs/collapse"],
  "dialog": ["@alpinejs/focus"]
}

```

--------------------------------

### Basis UI components.json Schema

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

This JSON file configures the Basis UI component library within an Astro project. It specifies the schema, styling, Tailwind CSS configuration (config file path and CSS file path), Alpine.js integration, and path aliases for components and utilities. This configuration is automatically generated and updated by the Basis UI CLI.

```json
{
  "$schema": "https://basis.zhengyishen.com/schema.json",
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/global.css"
  },
  "alpine": true,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}
```

--------------------------------

### Registry JSON Structure (registry/index.json)

Source: https://context7.com/zhengyishen0/basis-ui/llms.txt

Defines the structure and metadata for the UI component registry. It includes component details, dependencies, file information, and extracted import metadata. This schema is used to manage and discover available UI components and their requirements.

```json
{
  "$schema": "https://basis.zhengyishen.com/registry-schema.json",
  "version": "1.0.0",
  "ui": {
    "name": "ui",
    "description": "Complete UI component library for Astro + Alpine.js",
    "dependencies": [
      "class-variance-authority@^0.7.1",
      "astro-icon@^1.1.5"
    ],
    "files": [
      {
        "path": "ui",
        "type": "folder"
      }
    ]
  },
  "lib": {
    "utils": {
      "name": "utils",
      "description": "Utility functions for class name merging",
      "files": [
        {
          "path": "lib/utils.ts",
          "type": "lib"
        }
      ]
    },
    "component-variants": {
      "name": "component-variants",
      "description": "Shared component variant system",
      "dependencies": [],
      "registryDependencies": ["utils"],
      "files": [
        {
          "path": "lib/component-variants.ts",
          "type": "lib"
        }
      ]
    }
  },
  "meta": {
    "extractedImports": [
      "class-variance-authority",
      "astro-icon/components",
      "shiki"
    ],
    "scannedFiles": 150,
    "lastUpdated": "2025-01-15T12:00:00.000Z"
  }
}
```

--------------------------------

### Transform Relative Imports to Aliases (TypeScript)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/CLAUDE.md

This TypeScript code snippet demonstrates how to transform relative import paths within content to use aliases, specifically converting '../..' paths to '@/' paths. This is useful for standardizing import paths.

```typescript
// Transform relative imports to aliases
content = content.replace(
  /from ['"]\.\.\/\.\.\/lib\/utils['"];?/g, 
  'from "@/lib/utils";'
);
```

--------------------------------

### Tailwind Theme CSS Variables (CSS)

Source: https://github.com/zhengyishen0/basis-ui/blob/main/WARP.md

This CSS snippet illustrates the use of CSS variables for consistent theming within the project. It defines variables like `--primary` and `--secondary` with HSL color values, which can be used throughout the project for styling.

```css
/* CSS variables for consistent theming */
:root {
  --primary: 221.2 83.2% 53.3%;
  --secondary: 210 40% 96%;
  /* ... theme variables */
}

```