@magmonium/cli

A powerful and extensible asset compilation tool that can be shared across multiple projects. This tool intelligently processes all files in your mag_assets/ folder - compiling when possible, copying when needed.

Project Structure

This tool follows a simple but powerful convention:

• Source files go in mag_assets/ folders
• Compiled files are output to assets/ folders
• Files are automatically compiled if a compiler exists, otherwise copied directly

project/
├── mag_assets/          # Source files (tracked in Git)
│   ├── icons/          # SVG source files → compiled to JSON
│   ├── styles/         # SCSS/CSS source files → compiled
│   ├── i18n/          # Translation source files → compiled
│   ├── images/        # Image files → copied as-is
│   ├── docs/          # Documentation → copied as-is
│   └── ...            # Any other files → copied as-is
├── assets/             # Compiled files (ignored in Git)
│   ├── icons/         # Compiled SVG assets
│   ├── styles/        # Compiled CSS/SCSS
│   ├── i18n/         # Compiled translations
│   ├── images/       # Copied images
│   ├── docs/         # Copied documentation
│   └── ...           # All other copied files
└── mag-build.config.js # Build configuration (optional)

Quick Start

One Command Does Everything

# Install globally
npm install -g @magmonium/cli

# Build everything from mag_assets/ to assets/
mag-build build

# That's it! The tool will:
# ✅ Compile SVG files to JSON + sprite sheets
# ✅ Compile SCSS/CSS files to optimized CSS
# ✅ Compile translation files to flattened JSON + TypeScript definitions
# ✅ Copy all other files (images, docs, etc.) as-is

Local Installation

# Install as dependency
npm install @magmonium/cli

# Add to package.json
{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch"
  }
}

# Run
npm run build

Features

• 🚀 One Command: Single build command handles everything intelligently
• 🎨 SVG Compilation: Convert SVG files to JSON with sprite sheet generation
• 🎭 Theme Compilation: Process TypeScript/SCSS/CSS theme files into JSON and CSS formats
• 🌍 Translation Compilation: Handle i18n files with TypeScript definitions
• 📁 Smart Copying: Copy files that don't need compilation automatically
• 👀 Watch Mode: Real-time compilation on file changes
• 🔧 Zero Config: Works out of the box with sensible defaults
• 🔧 Configurable: Optional config file for advanced customization
• 📦 NPM Package: Easy installation and sharing across projects
• 🌐 Global CLI: Can be installed globally for system-wide access
• 📋 Tabs Compilation: Process tab configurations with smart navs/options reference resolution

CLI Commands

# Build everything (compile + copy)
mag-build build

# Watch for changes
mag-build build --watch

# Only copy files (skip compilation)
mag-build build --copy-only

Package.json Integration

Simple Setup (Recommended)

{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch"
  }
}

Complete Setup

{
  "scripts": {
    "build": "mag-build build",
    "dev": "mag-build build --watch",
    "copy": "mag-build build --copy-only"
  }
}

Configuration (Optional)

The tool works perfectly with zero configuration, but you can customize it:

// mag-build.config.js
module.exports = {
  svg: {
    inputPaths: ['./mag_assets/icons'],
    outputPath: './assets',
    spriteSheet: true,
    optimize: true,
  },
  theme: {
    inputPaths: ['./mag_assets/theme'],
    outputPath: './assets/theme',
    format: 'json',
    generateCSS: true,
  },
  i18n: {
    inputPaths: ['./mag_assets/i18n'],
    outputPath: './assets/i18n',
    defaultLocale: 'en',
    supportedLocales: ['en', 'es', 'fr'],
  },
  copy: {
    inputPaths: ['./mag_assets'],
    outputPath: './assets',
    patterns: ['**/*.png', '**/*.jpg', '**/*.pdf'], // Specific files only
    exclude: ['**/*.svg', '**/*.scss', '**/*.json'], // Exclude compiled files
    overwrite: true,
  },
};

How It Works

1. Scans mag_assets/ for all files
2. Compiles files with matching compilers:
   • .svg files → JSON + sprite sheets
   • .scss, .sass, .css files → optimized CSS
   • .json, .yaml, .yml translation files → flattened JSON + TypeScript definitions
3. Copies all other files directly to assets/
4. Maintains directory structure automatically

File Type Handling

| File Type | Action | Output | | ----------------------------- | ------- | -------------------------------------------- | | *.svg | Compile | JSON + sprite sheet | | *.ts (in theme/) | Compile | JSON + CSS (from TypeScript themes) | | *.scss, *.sass, *.css | Compile | Optimized CSS | | *.json, *.yaml (in i18n/) | Compile | Flattened JSON + TypeScript definitions | | *.yaml, *.yml (in tabs/) | Compile | Tab configurations with reference resolution | | *.yaml, *.yml (in navs/) | Compile | Navigation options for tab references | | *.png, *.jpg, *.gif | Copy | Unchanged | | *.md, *.txt, *.pdf | Copy | Unchanged | | All other files | Copy | Unchanged |

Tabs Compilation

The tabs compiler processes YAML files in the mag_assets/tabs/ directory and generates JSON tab configurations with intelligent reference resolution.

Basic Tab Configuration

# mag_assets/tabs/main-tabs.yaml
id: main-tabs
label: Main Navigation Tabs
orientation: horizontal
variant: underline
size: md
colorScheme: blue
isLazy: true
defaultIndex: 0
tabs:
  - id: home-tab
    label: Home
    icon:
      name: home
      color: blue
    link: /home
    description: Home page tab
  - id: about-tab
    label: About
    icon:
      name: info
      color: green
    link: /about
    description: About page tab

Smart Reference Resolution (navs → options fallback)

The tabs compiler intelligently resolves tab references with a navs-first, options-fallback strategy:

1. Primary: Looks in mag_assets/navs/ directory first
2. Fallback: Falls back to mag_assets/options/ directory if not found in navs

Navigation Items (navs/)

# mag_assets/navs/store-navs.yml
- - id: products
    label: Products
    icon:
      name: package
      color: blue
    link: /store/products
    description: Browse all products
  - id: categories
    label: Categories
    icon:
      name: grid
      color: green
    link: /store/categories
    description: Product categories

Tab Configuration with References

File-Level Reference (Recommended):

# mag_assets/tabs/store-tabs.yaml
id: store-tabs
label: Store Navigation
tabs: store # References entire store.yml file
color: mm # Additional styling properties
variant: pills
align: center

Individual References:

# mag_assets/tabs/mixed-tabs.yaml
id: mixed-tabs
label: Mixed Navigation
tabs:
  - '@store-navs:products' # Resolves from navs directory (primary)
  - '@store-options:deals' # Falls back to options directory
  - id: inline-tab
    label: Custom Tab
    link: /custom

Generated Output

{
  "id": "store-tabs",
  "label": "Store Navigation",
  "tabs": [
    {
      "id": "products",
      "label": "Products",
      "icon": { "name": "package", "color": "blue" },
      "link": "/store/products",
      "description": "Browse all products"
    },
    {
      "id": "deals",
      "label": "Special Deals",
      "icon": { "name": "percent", "color": "red" },
      "link": "/store/deals",
      "description": "Limited time offers"
    },
    {
      "id": "inline-tab",
      "label": "Custom Tab",
      "link": "/custom"
    }
  ]
}

Reference Formats

• tabs: filename - References entire file from navs/ first, then options/ (file-level reference)
• @filename:option-id - References an option by ID from the specified file
• @filename:0:2 - References using array indices (advanced usage)
• filename - References all options from the specified file

Configuration Properties

Tab configurations support the following properties:

id: string # Required: Unique identifier
label: string # Required: Display label
tabs: string | array # Required: File reference or tab array
orientation: horizontal | vertical # Optional: Tab layout
variant: default | underline | pills | enclosed | soft-rounded # Optional: Visual style
size: sm | md | lg # Optional: Size variation
colorScheme: string # Optional: Color scheme
color: string # Optional: Custom color
align: left | center | right # Optional: Alignment
isLazy: boolean # Optional: Lazy loading
defaultIndex: number # Optional: Default active tab
onChange: string # Optional: Change handler

Directory Structure

mag_assets/
├── tabs/           # Tab configurations
│   ├── main-tabs.yaml
│   └── store-tabs.yaml
├── navs/           # Navigation items (primary source)
│   ├── main-navs.yml
│   └── store-navs.yml
└── options/        # General options (fallback source)
    ├── store-options.yml
    └── form-options.yml

Benefits

• Simple File References: Use tabs: filename for clean, simple configuration
• Logical Separation: Keep navigation items separate from general options
• Smart Fallback: Automatically falls back to options if navs don't exist
• Backward Compatible: Existing @options:... references continue to work
• Flexible: Supports file-level references, individual references, and inline definitions
• Enhanced Styling: Additional properties like color and align for custom styling

Using in Multiple Projects

Global Installation (Recommended)

# Install once globally
npm install -g @magmonium/cli

# Use in any project
cd ~/project-a && mag-build build
cd ~/project-b && mag-build build

Project-Specific Installation

# Install per project
npm install @magmonium/cli

# Use with npx
npx mag-build build

Benefits

1. Zero Mental Overhead: Just run build and everything works
2. Intelligent Processing: Compiles when possible, copies otherwise
3. No Configuration Required: Works out of the box with sensible defaults
4. Clear Separation: Source files (mag_assets/) vs generated files (assets/)
5. Version Control Friendly: Only source files are tracked
6. Build Process Consistency: Same mag_assets/ → assets/ workflow everywhere
7. Flexibility: Handles any file type - compiles or copies as appropriate

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.