d523f0f600
Document application modes (development/debug/production) Add global file drop handler, order column normalization, SPA hash fix Serve CDN assets via /_vendor/ URLs instead of merging into bundles Add production minification with license preservation Improve JSON formatting for debugging and production optimization Add CDN asset caching with CSS URL inlining for production builds Add three-mode system (development, debug, production) Update Manifest CLAUDE.md to reflect helper class architecture Refactor Manifest.php into helper classes for better organization Pre-manifest-refactor checkpoint: Add app_mode documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
258 lines
9.0 KiB
Plaintext
Executable File
258 lines
9.0 KiB
Plaintext
Executable File
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
|
|
- ajax_disable_batching flag
|
|
- Other debug-only properties
|
|
|
|
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)
|