rspade_system/app/RSpade/man/bundle_api.txt

BUNDLE_API(3)                  RSX Framework Manual                  BUNDLE_API(3)

NAME
    Bundle - RSX asset compilation and management system

SYNOPSIS
    use App\RSpade\Core\Bundle\Rsx_Bundle_Abstract;

    class My_Bundle extends Rsx_Bundle_Abstract
    {
        public static function define(): array
        {
            return [
                'include' => [
                    'jquery',               // Module alias
                    'Bootstrap5_Bundle',    // Bundle class
                    'rsx/app/myapp',       // Directory
                    'rsx/lib/utils.js',    // Specific file
                ],
            ];
        }
    }

    // Render in Blade
    {!! My_Bundle::render() !!}

DESCRIPTION
    RSX Bundles provide a radically simplified asset compilation system
    compared to Laravel Mix or Vite. Instead of webpack configurations,
    JSON manifests, and build scripts, you define a simple PHP class
    with an array of what to include. The framework handles everything
    else automatically.

    Unlike Laravel's approach where you configure webpack, define entry
    points, set up hot module replacement, and manage complex build
    pipelines, RSX Bundles use a single 'include' array that accepts
    any mix of directories, files, NPM packages, or other bundles.
    The system automatically determines file types, resolves dependencies,
    and compiles everything.

    The Bundle system integrates directly with the Manifest, automatically
    including JavaScript stubs for controllers and models. SCSS files are
    compiled transparently. Vendor and application code are automatically
    split for optimal caching.

    Key differences from Laravel Mix/Vite:
    - Laravel: Complex webpack.mix.js or vite.config.js files
    - RSX: Simple PHP class with an include array

    - Laravel: Manual configuration of entry points and outputs
    - RSX: Automatic detection and compilation

    - Laravel: Separate processes for JS bundling and CSS compilation
    - RSX: Unified system handles all asset types

    - Laravel: Manual versioning and cache busting setup
    - RSX: Automatic hash-based cache busting

    Benefits:
    - No JavaScript build configuration needed
    - Works immediately without npm run dev/build
    - Automatic vendor/app code splitting
    - Integrated with PHP class discovery
    - Zero configuration SCSS compilation

CREATING A BUNDLE
    1. Extend Rsx_Bundle_Abstract
    2. Implement define() method
    3. Return configuration array with 'include' key

    Example:
        class Dashboard_Bundle extends Rsx_Bundle_Abstract
        {
            public static function define(): array
            {
                return [
                    'include' => [
                        'jquery',
                        'lodash',
                        'bootstrap5',
                        'rsx/app/dashboard',
                    ],
                    'config' => [
                        'api_version' => '2.0',
                    ],
                ];
            }
        }

INCLUDE TYPES
    Module Aliases
        Predefined in config/rsx.php:
        'jquery', 'lodash', 'bootstrap5', 'vue', 'react'

    Bundle Classes
        Reference other bundles:
        'Core_Bundle', 'Bootstrap5_Src_Bundle'

    Bundle Aliases
        Defined in config/rsx.php:
        'bootstrap5_src' => Bootstrap5_Src_Bundle::class

    Directories
        Include all files recursively:
        'rsx/app/dashboard'

    Specific Files
        Include individual files:
        'rsx/lib/utils.js'
        'rsx/theme/variables.scss'

    NPM Modules
        Include from node_modules:
        'npm:axios'
        'npm:moment'

    CDN Assets
        External resources:
        'cdn:https://unpkg.com/library.js'

BUNDLE RENDERING
    In Blade layouts/views:
        {!! Dashboard_Bundle::render() !!}

    Generates:
        <link href="/bundles/Dashboard__vendor.abc123.css" rel="stylesheet">
        <link href="/bundles/Dashboard__app.def456.css" rel="stylesheet">
        <script src="/bundles/Dashboard__vendor.abc123.js"></script>
        <script src="/bundles/Dashboard__app.def456.js"></script>

    Never call from controllers - only from Blade files.

VENDOR/APP SPLIT
    Files automatically split:
    - vendor/: Files containing "vendor/" in path, NPM modules
    - app/: Everything else

    Benefits:
    - Vendor files cached longer (rarely change)
    - App files rebuilt on changes
    - Smaller incremental builds

BUNDLE PROCESSORS
    Transform files during compilation.
    Configured globally in config/rsx.php.

    Built-in processors:
    - ScssProcessor: .scss → .css
    - JqhtmlProcessor: .jqhtml → JavaScript

    All processors receive ALL collected files,
    decide what to process based on extension.

CREATING A PROCESSOR
    class MyProcessor extends AbstractBundleProcessor
    {
        public static function get_name(): string
        {
            return 'myprocessor';
        }

        public static function get_extensions(): array
        {
            return ['myext'];  // Extensions to process
        }

        public static function process(string $file, array $options = []): ?array
        {
            $content = file_get_contents($file);

            // Transform content
            $processed = transform($content);

            return [
                'content' => $processed,
                'extension' => 'js',  // Output extension
            ];
        }
    }

    Register in config/rsx.php:
        'bundle_processors' => [
            App\RSpade\Processors\MyProcessor::class,
        ],

COMPILATION PROCESS
    1. Resolve all includes to file list
    2. Split into vendor/app buckets
    3. Check cache (skip if unchanged)
    4. Run processors on files
    5. Add JavaScript stubs from manifest
    6. Filter to JS/CSS only
    7. Compile vendor and app separately
    8. In production: concatenate into single files

JAVASCRIPT STUBS
    Controllers with Ajax_Endpoint methods get stubs:
        // Automatically included in bundles
        class User_Controller {
            static async get_profile(...args) {
                return Ajax.call('User_Controller', 'get_profile', args);
            }
        }

    Models with fetch() methods get stubs:
        class User_Model {
            static async fetch(id) {
                return Ajax.model_fetch('User_Model', id);
            }
        }

CONFIGURATION
    Bundle config added to window.rsxapp:
        'config' => [
            'feature_flags' => ['new_ui'],
            'api_version' => '2.0',
        ]

    Access in JavaScript:
        if (window.rsxapp.config.feature_flags.includes('new_ui')) {
            // New UI code
        }

CACHING
    Development:
        - Vendor files cached until dependencies change
        - App files rebuilt on any change
        - Cache keys based on file hashes

    Production:
        - All files concatenated and minified
        - Cache forever with hash in filename
        - Rebuild only via rsx:bundle:compile

REQUIRED BUNDLES
    Automatically included if used:
    - jquery (if $ or jQuery detected)
    - lodash (if _ detected)
    - jqhtml (if .jqhtml files present)

FILE ORGANIZATION
    storage/rsx-build/bundles/
    ├── Dashboard__vendor.abc123.js
    ├── Dashboard__vendor.abc123.css
    ├── Dashboard__app.def456.js
    └── Dashboard__app.def456.css

    Hash changes when content changes.

EXAMPLES
    // Kitchen sink bundle
    class App_Bundle extends Rsx_Bundle_Abstract
    {
        public static function define(): array
        {
            return [
                'include' => [
                    // Required modules
                    'jquery',
                    'lodash',
                    'bootstrap5',

                    // Other bundles
                    'Core_Bundle',

                    // Application code
                    'rsx/app',
                    'rsx/lib',

                    // Specific overrides
                    'rsx/theme/variables.scss',

                    // NPM packages
                    'npm:axios',
                    'npm:chart.js',
                ],
                'config' => [
                    'app_name' => 'MyApp',
                    'version' => '1.0.0',
                ],
            ];
        }
    }

    // Module-specific bundle
    class Admin_Bundle extends Rsx_Bundle_Abstract
    {
        public static function define(): array
        {
            return [
                'include' => [
                    __DIR__,  // Include bundle's directory
                    'rsx/lib/admin',
                ],
            ];
        }
    }

CIRCULAR DEPENDENCIES
    Framework detects and prevents circular includes:
    - A includes B, B includes A = error
    - Shows clear error with dependency chain

TROUBLESHOOTING
    Bundle not updating:
        php artisan rsx:bundle:compile My_Bundle --force

    Missing files:
        Check paths are relative to project root.
        Verify files exist in manifest.

    Processor not running:
        Check processor registered in config.
        Verify file extension matches.

SEE ALSO
    manifest_api(3), jqhtml(3), controller(3)

RSX Framework                     2025-09-17                      BUNDLE_API(3)