Skip to content

PRESETS_GUIDE.md

Latest commit

 

History

History
313 lines (253 loc) · 7.35 KB

PRESETS_GUIDE.md

File metadata and controls

313 lines (253 loc) · 7.35 KB
Raw

Presets Feature Guide

Overview

Presets allow you to define multiple packaging configurations in a single .packaide.json file. Each preset can override base configuration options, making it easy to create different builds for different scenarios.

How It Works

  1. Base Configuration: Define your default/common settings at the root level
  2. Presets: Define named configurations that override base settings
  3. Usage: Run packaide with a specific preset using the --preset flag

Configuration Structure

{
  "outputPath": "release",
  "folders": ["src", "public", "themes"],
  "files": ["index.html"],
  "exclude": [],
  "include": ["**/*"],
  "archiveAfterCopy": true,
  "archiveName": "webapp-default",
  
  "presets": {
    "preset-name": {
      "outputPath": "release-custom",
      "exclude": ["themes/dark/**"],
      "archiveName": "webapp-preset"
    }
  }
}

Base Configuration (Root Level)

These are your default settings that apply when no preset is specified:

  • outputPath - Where to output packaged files
  • folders - Array of folders to include
  • files - Array of individual files to include
  • exclude - Array of glob patterns to exclude
  • include - Array of glob patterns to include
  • archiveAfterCopy - Whether to create a ZIP archive
  • archiveName - Name of the archive file
  • ftp - FTP upload configuration

Preset Configuration

Each preset can override any base configuration property. Only include the properties you want to override.

Example: Web App with Multiple Themes

{
  "outputPath": "release",
  "folders": ["src", "public", "themes", "assets"],
  "files": ["index.html", "package.json"],
  "exclude": [],
  "include": ["**/*"],
  "archiveAfterCopy": true,
  "archiveName": "webapp-default",
  
  "presets": {
    "light-theme": {
      "exclude": [
        "themes/dark-theme/**",
        "themes/admin-theme/**"
      ],
      "archiveName": "webapp-light",
      "outputPath": "release-light"
    },
    
    "dark-theme": {
      "exclude": [
        "themes/light-theme/**",
        "themes/admin-theme/**"
      ],
      "archiveName": "webapp-dark",
      "outputPath": "release-dark"
    },
    
    "admin-only": {
      "folders": ["src/admin", "themes/admin-theme"],
      "exclude": ["themes/light-theme/**", "themes/dark-theme/**"],
      "archiveName": "webapp-admin"
    },
    
    "production": {
      "exclude": [
        "**/test/**",
        "**/*.test.js",
        "**/*.spec.js",
        "**/docs/**"
      ],
      "archiveAfterCopy": true,
      "archiveName": "webapp-production"
    }
  }
}

CLI Usage

Run with Default Configuration

packaide copy

Uses the base configuration (root level settings).

Run with a Preset

packaide copy --preset light-theme
packaide copy -p dark-theme

Upload with a Preset

packaide upload --preset production
packaide upload -p admin-only

Examples

Example 1: Theme Selection for E-commerce Site

{
  "folders": ["app", "public", "themes"],
  "exclude": [],
  "archiveName": "ecommerce-site",
  
  "presets": {
    "summer-sale": {
      "exclude": ["themes/winter/**", "themes/halloween/**"],
      "archiveName": "ecommerce-summer"
    },
    "winter-sale": {
      "exclude": ["themes/summer/**", "themes/halloween/**"],
      "archiveName": "ecommerce-winter"
    },
    "black-friday": {
      "exclude": ["themes/summer/**", "themes/winter/**"],
      "archiveName": "ecommerce-blackfriday"
    }
  }
}

Usage:

packaide copy --preset summer-sale
packaide copy --preset winter-sale
packaide copy --preset black-friday

Example 2: Client-Specific Builds

{
  "folders": ["src", "assets", "themes"],
  "files": ["index.html"],
  "archiveName": "app-generic",
  
  "presets": {
    "client-a": {
      "folders": ["src", "assets", "themes/client-a"],
      "exclude": ["themes/client-b/**", "themes/client-c/**"],
      "archiveName": "app-client-a",
      "outputPath": "builds/client-a"
    },
    "client-b": {
      "folders": ["src", "assets", "themes/client-b"],
      "exclude": ["themes/client-a/**", "themes/client-c/**"],
      "archiveName": "app-client-b",
      "outputPath": "builds/client-b"
    }
  }
}

Example 3: Environment-Based Builds

{
  "folders": ["src", "public"],
  "files": ["index.html", "package.json"],
  
  "presets": {
    "development": {
      "exclude": [],
      "archiveAfterCopy": false,
      "outputPath": "dev-build"
    },
    "staging": {
      "exclude": ["**/test/**", "**/*.test.js"],
      "archiveAfterCopy": true,
      "archiveName": "app-staging",
      "outputPath": "staging-build"
    },
    "production": {
      "exclude": [
        "**/test/**",
        "**/*.test.js",
        "**/*.spec.js",
        "**/docs/**",
        "**/.env.development"
      ],
      "archiveAfterCopy": true,
      "archiveName": "app-production",
      "outputPath": "production-build"
    }
  }
}

Usage:

packaide copy --preset development
packaide copy --preset staging
packaide copy --preset production

Preset Override Rules

  1. Preset values always override base values
  2. Only specified properties are overridden - other properties use base values
  3. Arrays are completely replaced - not merged
  4. Nested objects (like ftp) can be partially overridden

Override Example:

Config:

{
  "folders": ["src", "public", "themes"],
  "exclude": ["**/node_modules/**"],
  "archiveName": "default",
  
  "presets": {
    "minimal": {
      "folders": ["src"],
      "archiveName": "minimal-build"
    }
  }
}

Result when using --preset minimal:

  • folders: ["src"] ← Overridden
  • exclude: ["**/node_modules/**"] ← Inherited from base
  • archiveName: "minimal-build" ← Overridden

List Available Presets

If you run with a non-existent preset, packaide will show available presets:

packaide copy --preset nonexistent

Output:

Preset 'nonexistent' not found in config.
Available presets: light-theme, dark-theme, admin-only, production

Best Practices

  1. Use base config for common settings - Put shared configuration at the root level
  2. Keep presets focused - Only override what's different
  3. Use descriptive names - Make preset names self-explanatory
  4. Test each preset - Verify each preset produces the expected output
  5. Document your presets - Add comments in your config (outside JSON) or in README

Tips

  • Presets are perfect for multi-tenant applications
  • Use presets for different deployment environments
  • Create presets for different client builds
  • Combine presets with exclude/include patterns for maximum flexibility
  • Each preset can have its own outputPath to avoid overwriting builds

Common Use Cases

✅ Multiple theme variations
✅ Client-specific customizations
✅ Environment-based builds (dev/staging/prod)
✅ Feature-toggled builds
✅ Regional/localized versions
✅ Different package sizes (full/lite versions)

Workflow Example

# Development - quick build without archiving
packaide copy --preset development

# Test build for client A
packaide copy --preset client-a

# Production build with all optimizations
packaide copy --preset production

# Upload staging build to FTP
packaide upload --preset staging

That's it! Presets make it easy to manage multiple build configurations in one place. 🎉