@galaxy-stack/nebula-cli

v1.1.0

Published

3 days ago

Nebula CLI — add Galaxy UI components to your Vue, React, Angular, Next.js, Nuxt.js, React Native, or Flutter project

Downloads

232

Nebula CLI

CLI for initializing Galaxy UI and copying framework-specific components (67 components × 5 frameworks: React, Vue, Angular, React Native, Flutter) into your project.

Features

Commands: init, add, list, doctor, diff, update, migrate tailwind
Detects React, Next.js, Vue, Nuxt.js, and Angular projects
Stores project settings in components.json
Scaffolds Tailwind in v4-first mode while preserving existing v3 projects
Copies components into your source tree so they remain editable
Fails clearly when remote component files cannot be fetched
Theme presets: init --theme violet|green|blue|default
Integrity-verified registry CDN (sha256 per file + release digest)

Changelog

See CHANGELOG.md — current version 1.0.0 (Nebula milestone).

Framework Mapping

nextjs and nuxtjs are CLI target frameworks, not separate published component packages.

nextjs reuses the React source registry and adds Next-specific transforms such as 'use client' when required
nuxtjs reuses the Vue source registry and keeps Vue/Nuxt-specific file structure intact

That means the package/source-of-truth layer is still React for Next.js and Vue for Nuxt.js, while the CLI adapts the copied files for the target app.

Installation

npx @galaxy-stack/nebula-cli@latest init

Or install globally:

npm install -g @galaxy-stack/nebula-cli
bun add -g @galaxy-stack/nebula-cli

Quick Start

1. Initialize

npx @galaxy-stack/nebula-cli@latest init

init currently does the following:

Detects the framework
Creates components.json
Installs core dependencies
Creates components/ui and the cn() utility
Detects Tailwind v3/v4 and scaffolds the matching mode

Tailwind behavior:

Existing Tailwind v3 project: stays on v3
Existing Tailwind v4 project: stays on v4
No Tailwind detected: installs/scaffolds v4 by default

1.5 Migrate Tailwind v3 To v4

npx @galaxy-stack/nebula-cli@latest migrate tailwind --dry-run
npx @galaxy-stack/nebula-cli@latest migrate tailwind --yes

migrate tailwind currently focuses on the safe scaffold layer:

Detects whether the current project still uses Tailwind v3
Rewrites the global CSS entry from @tailwind ... directives to @import "tailwindcss";
Rewrites the PostCSS config to use @tailwindcss/postcss
Updates components.json Tailwind version metadata when present
Reports utility classes that may need manual review in Tailwind v4

It does not try to auto-rewrite every potentially breaking utility class.

2. Add Components

# Add one component
npx @galaxy-stack/nebula-cli@latest add button

# Add several components
npx @galaxy-stack/nebula-cli@latest add button input card

# Interactive selection
npx @galaxy-stack/nebula-cli@latest add

# Add everything in the current registry
npx @galaxy-stack/nebula-cli@latest add --all

Available Components

🎨 Form Components (9)

button - Versatile button with variants and sizes
input - Text input with label and validation states
checkbox - Checkbox with indeterminate state
radio-group - Radio button groups
select - Dropdown select with search
slider - Range slider input
switch - Toggle switch
textarea - Multi-line text input
label - Accessible form labels

📐 Layout Components (4)

separator - Horizontal/vertical divider
accordion - Collapsible content sections
collapsible - Single collapsible panel
tabs - Tabbed content organization

🧭 Navigation Components (4)

navigation-menu - Complex navigation with dropdowns
menubar - Desktop-style menu bar
context-menu - Right-click context menus
dropdown-menu - Action dropdown menus

🔔 Overlay Components (5)

dialog - Modal dialogs
alert-dialog - Confirmation dialogs
popover - Floating content containers
tooltip - Hover tooltips
hover-card - Preview cards on hover

📊 Data Display Components (6)

avatar - User avatars with fallbacks
progress - Progress bars and indicators
table - Data tables with sorting
pagination - Page navigation
empty - Empty state placeholders
skeleton - Loading skeletons

✍️ Typography & Utilities (2)

typography - Text styles and components
kbd - Keyboard shortcut display

📅 Date & Time Components (2)

calendar - Date picker calendar
calendar-range - Date range picker

⚡ Advanced Components (4)

command - Command palette (⌘K)
sheet - Slide-out panels
toolbar - Action toolbars
tags-input - Multi-value tag input

🎁 Bonus Components (5)

aspect-ratio - Aspect ratio container
badge - Status badges and labels
card - Content cards
scroll-area - Custom scrollbars
toggle - Toggle buttons
toggle-group - Toggle button groups

Framework Examples

React

import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

export function MyComponent() {
  return (
    <div>
      <Button variant="default" size="lg">
        Click me
      </Button>
      <Input placeholder="Enter text..." />
    </div>
  );
}

Vue

<script setup lang="ts">
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
</script>

<template>
  <div>
    <Button variant="default" size="lg">Click me</Button>
    <Input placeholder="Enter text..." />
  </div>
</template>

Angular

import { Component } from '@angular/core';
import { ButtonDirective } from '@/components/ui/button';
import { InputComponent } from '@/components/ui/input';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [ButtonDirective, InputComponent],
  template: `
    <div>
      <button hlmBtn variant="default" size="lg">Click me</button>
      <hlm-input placeholder="Enter text..." />
    </div>
  `,
})
export class MyComponent {}

Next.js

'use client';

import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

export default function MyComponent() {
  return (
    <div>
      <Button variant="default" size="lg">
        Click me
      </Button>
      <Input placeholder="Enter text..." />
    </div>
  );
}

add automatically preserves framework-specific transformations such as 'use client' for Next.js components when needed.

Next.js support is implemented as a React-source target inside the CLI, not as a separate @galaxy-ui/nextjs package.

Nuxt.js

<script setup lang="ts">
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
</script>

<template>
  <div>
    <Button variant="default" size="lg">Click me</Button>
    <Input placeholder="Enter text..." />
  </div>
</template>

Nuxt users should make sure the @/ alias is available in nuxt.config.ts.

Nuxt.js support is implemented as a Vue-source target inside the CLI, not as a separate @galaxy-ui/nuxtjs package.

Configuration

Galaxy UI stores project settings in components.json:

{
  "$schema": "https://galaxy-nebula.vercel.app/schema.json",
  "framework": "react",
  "typescript": true,
  "tailwind": {
    "version": 4,
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib"
  },
  "iconLibrary": "lucide"
}

Configuration Options

| Option | Description | Default | | -------------------- | ---------------------- | ------------------ | | framework | Your framework | Auto-detected | | typescript | Use TypeScript | true | | tailwind.version | Tailwind major version | Auto-detected | | tailwind.config | Tailwind config path | Framework-specific | | tailwind.css | Global CSS file | Framework-specific | | tailwind.baseColor | Base color scheme | slate | | aliases.components | Components alias | @/components | | aliases.utils | Utils alias | @/lib/utils | | iconLibrary | Icon library to use | lucide |

CLI Commands

`init`

Initialize Galaxy UI in your project and scaffold components.json.

npx @galaxy-stack/nebula-cli@latest init

# Skip prompts (use defaults)
npx @galaxy-stack/nebula-cli@latest init --yes

`add`

Add registry components to your project.

# Interactive mode
npx @galaxy-stack/nebula-cli@latest add

# Add specific components
npx @galaxy-stack/nebula-cli@latest add button input

# Add all components
npx @galaxy-stack/nebula-cli@latest add --all

There is currently no diff command and no --overwrite option on add.

Styling And Theming

Galaxy UI uses Tailwind CSS with CSS variables for theming. After running init, you can customize colors in your CSS file:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    /* ... more variables */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode variables */
  }
}

Customization

Components are copied to your project, so you have full control:

Modify components - Edit any component in components/ui/
Change styles - Update Tailwind classes or CSS variables
Add features - Extend components with your own functionality
No lock-in - Components are yours to modify

Documentation

Docs Website: https://galaxy-nebula.vercel.app
Repository: https://github.com/galaxy-nebula/galaxy-design-cli

Notes

add currently fetches component source files from GitHub at runtime.
The CLI now fails explicitly if required files cannot be fetched.
components.json is the active configuration system. Legacy galaxy.config.* flow has been removed from source.

License

MIT License - see LICENSE for details