rspade_system/app/RSpade/man/app_mode.txt

APP_MODE(3)                 RSX Framework Manual                 APP_MODE(3)

NAME
    app_mode - Application execution modes and production build system

SYNOPSIS
    Environment:
        RSX_MODE=development|debug|production

    Commands:
        php artisan rsx:mode:set <mode>
        php artisan rsx:prod:build
        php artisan rsx:prod:export [--path=./rsx-export]

DESCRIPTION
    RSpade supports three execution modes that control build behavior,
    optimization level, and debugging capabilities. RSX_MODE is the
    authoritative source of truth for application mode, taking precedence
    over Laravel's APP_ENV setting.

    The mode system enables a single codebase to run efficiently in
    development (with automatic rebuilds and debugging tools) and
    production (with pre-built optimized assets and caching).

MODES
    development
        Default mode for local development.

        - Manifest rebuilds automatically on file changes
        - Bundles compile JIT on web request
        - Source maps included inline
        - CDN assets loaded directly from remote URLs
        - console_debug() output appears in browser console
        - Debug info included in window.rsxapp
        - Laravel caches disabled (config, routes, views)
        - File change detection active

    debug
        Production-like mode with debugging aids for troubleshooting
        production-specific issues.

        - All production optimizations applied
        - Source maps included inline (for debugging minified code)
        - CDN assets loaded directly from remote URLs
        - console_debug() calls remain in source (not stripped)
        - Debug info excluded from window.rsxapp
        - Requires pre-built assets (no automatic rebuilds)
        - Errors if build artifacts missing

    production
        Full production mode for deployed applications.

        - All production optimizations applied
        - No source maps
        - CDN assets cached locally and compiled into bundles
        - console_debug() calls stripped from source via Babel
        - Debug info excluded from window.rsxapp
        - JS/CSS minified
        - All JS merged into single file per bundle
        - All CSS merged into single file per bundle
        - Laravel caches enabled (config, routes, views)
        - Requires pre-built assets (no automatic rebuilds)
        - Errors if build artifacts missing

MODE COMPARISON
    Feature                    development  debug  production
    -------                    -----------  -----  ----------
    Auto manifest rebuild      Yes          No     No
    Auto bundle compile        Yes          No     No
    Inline source maps         Yes          Yes    No
    Minified output            No           Yes    Yes
    Merged JS/CSS files        No           No     Yes
    CDN assets bundled         No           No     Yes
    console_debug() in source  Yes          Yes    No (stripped)
    Debug in window.rsxapp     Yes          No     No
    Laravel caches             No           Yes    Yes
    Error if artifacts missing No           Yes    Yes

COMMANDS
    rsx:mode:set <mode>
        Change the application mode. Accepts: dev, development, debug,
        prod, production.

        This command:
        1. Updates RSX_MODE in .env file
        2. Clears all build artifacts (rsx:clean)
        3. For development: Runs rsx:bundle:compile --all
        4. For debug/production: Runs rsx:prod:build

        Example:
            php artisan rsx:mode:set production
            php artisan rsx:mode:set dev

    rsx:prod:build
        Build all production assets. Required before running in debug
        or production mode.

        This command:
        1. Rebuilds manifest with production settings
        2. Compiles all bundles with minification
        3. For production mode only:
           - Fetches and caches all CDN assets
           - Merges JS files into single bundle file
           - Merges CSS files into single bundle file
           - Strips console_debug() calls via Babel
        4. Runs Laravel cache commands:
           - php artisan config:cache
           - php artisan route:cache
           - php artisan view:cache

        Options:
            --force     Force rebuild even if artifacts exist

    rsx:prod:export [--path=PATH]
        Export the application for deployment. Runs rsx:prod:build
        first, then copies all necessary files to the export directory.

        Default path: ./rsx-export

        Included in export:
            /system/          Framework code
            /rsx/             Application code
            /rsx-build/       Compiled assets
            /node_modules/    Node dependencies
            /vendor/          Composer dependencies
            /*.json           Root JSON files (package.json, etc.)

        Excluded from export:
            .env              Security - must be configured per environment
            /storage/         User uploads and application storage
            /rsx-tmp/         Temporary build caches
            /rsx-export/      Previous exports

        After export, the destination can be deployed via CI/CD to
        production servers. The destination server must have its own
        .env file configured.

CDN ASSET HANDLING
    In development and debug modes, CDN assets (Bootstrap, jQuery, etc.)
    are loaded directly from their remote URLs as defined in bundles.

    In production mode, CDN assets are:
    1. Fetched via curl during rsx:prod:build
    2. Cached locally in /rsx-tmp/cdn_cache/ using URL-derived filenames
    3. Compiled directly into the merged bundle output

    Cache filenames are generated by hashing the full CDN URL, ensuring
    that URL changes (e.g., version upgrades) automatically trigger
    re-fetching without manual cache invalidation.

    Example:
        URL: https://cdn.example.com/lib@1.0.0/lib.min.js
        Cache: /rsx-tmp/cdn_cache/a3f8b2c1d4e5.js (hash of URL)

    When the bundle definition changes to @1.1.0, a new cache file is
    created and the old version is no longer referenced.

BABEL TRANSFORMATIONS
    Production builds use the rspade_prod Babel plugin to perform
    code transformations:

    console_debug() removal
        All console_debug() function calls are stripped from the
        source code in production mode. This includes:
        - console_debug('message')
        - console_debug('tag', data)
        - console_debug() with any arguments

        The calls are completely removed, not replaced with no-ops,
        resulting in smaller bundle sizes.

    Future transformations may be added to this plugin as needed.

WINDOW.RSXAPP IN PRODUCTION
    In debug and production modes, the following are excluded from
    window.rsxapp output:

        - console_debug configuration
        - Other debug-only properties

    The ajax_batching flag is always present but mode-dependent:
        - development: false (direct calls for easier debugging)
        - debug/production: true (batched calls for efficiency)

    Core functionality (user, site, csrf, params, etc.) remains
    available for application code.

DEPLOYMENT WORKFLOW
    Typical deployment process:

    1. Development
        RSX_MODE=development (default)
        - Code changes reflect immediately
        - Full debugging capabilities

    2. Pre-deployment testing
        php artisan rsx:mode:set debug
        - Test with production optimizations
        - Source maps available for debugging

    3. Build for production
        php artisan rsx:mode:set production
        - Or: php artisan rsx:prod:build

    4. Export for deployment
        php artisan rsx:prod:export
        - Creates ./rsx-export/ with all necessary files

    5. Deploy
        - Copy rsx-export/ to production server
        - Configure .env on production server
        - Point web server to deployment

    6. Return to development
        php artisan rsx:mode:set development
        - Clears production artifacts
        - Re-enables automatic rebuilding

CONFIGURATION
    .env file:
        RSX_MODE=development    # development|debug|production

    The RSX_MODE value is read by the framework at boot time and
    determines all build and runtime behavior. Laravel's APP_ENV
    and APP_DEBUG settings are respected for their own purposes
    but RSX_MODE is authoritative for RSpade-specific behavior.

ERROR HANDLING
    In debug and production modes, if required build artifacts are
    missing, the framework throws an error rather than attempting
    to build them automatically.

    Common errors:

        "Manifest not built for production mode"
            Run: php artisan rsx:prod:build

        "Bundle 'X' not compiled for production mode"
            Run: php artisan rsx:prod:build

        "CDN asset not cached: [url]"
            Run: php artisan rsx:prod:build --force

    These errors prevent accidental performance degradation from
    JIT compilation in production environments.

GITIGNORE
    Add to .gitignore:
        /rsx-export/

    The export directory should not be committed to version control.
    Each deployment should generate a fresh export.

SEE ALSO
    bundle_api(3), manifest(3)

AUTHOR
    RSpade Framework

RSpade                         January 2026                     APP_MODE(3)