rspade_system/docs/QUICKSTART.md

RSpade Framework - Quick Start Guide

Installation

Clone the Repository

Clone the RSpade project with the framework submodule:

git clone --recurse-submodules ssh://git@privategit.hanson.xyz:3322/brianhansonxyz/rspade_project.git /path/to/project
cd /path/to/project

Alternative method (clone then initialize submodules):

git clone ssh://git@privategit.hanson.xyz:3322/brianhansonxyz/rspade_project.git /path/to/project
cd /path/to/project
git submodule update --init --recursive

The --recurse-submodules flag automatically initializes and clones the system directory, which contains the RSpade framework.

Initial Setup

1. Copy environment configuration:

   cp system/.env.dist system/.env
   

2. Configure your database in system/.env:

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=your_database
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   

3. Install dependencies:

   cd system
   composer install
   npm install
   

4. Generate application key:

   php artisan key:generate
   

5. Run migrations:

   php artisan migrate
   

6. Build the manifest:

   php artisan rsx:manifest:build
   

Updating the Framework

The framework is managed as a git submodule in the system directory. To pull framework updates:

php artisan rsx:framework:pull

This command:

• Fetches updates from the upstream framework repository
• Applies updates while preserving your application code in ./rsx
• Rebuilds manifests and bundles automatically

Note: The system submodule is preconfigured with both origin and rspade_upstream remotes pointing to the framework repository. The rsx:framework:pull command uses rspade_upstream to check for and apply updates.

Your First Module

Create a simple module to verify everything works:

php artisan rsx:app:module:create welcome

This creates:

• /rsx/app/welcome/welcome_controller.php - Controller with routes
• /rsx/app/welcome/welcome_view.blade.php - Blade template
• /rsx/app/welcome/welcome.js - JavaScript class
• /rsx/app/welcome/welcome.scss - Styles

Visit http://your-domain/welcome to see your new module.

Essential Commands

Development

php artisan rsx:check              # Check code quality
php artisan rsx:routes             # View all routes
php artisan rsx:debug /route       # Test a route
php artisan rsx:manifest:build     # Rebuild manifest

Creating Structure

php artisan rsx:app:module:create <name>              # Create new module
php artisan rsx:app:module:feature:create <m> <f>     # Add feature to module
php artisan rsx:app:component:create --name=<name>    # Create jqhtml component

Database

php artisan make:migration:safe create_table_name     # Create migration
php artisan migrate                                    # Run migrations
php artisan db:query "SELECT * FROM users" --json     # Query database

Next Steps

• Read ./docs/CLAUDE.dist.md for comprehensive framework documentation
• Explore the demo module at /rsx/app/demo/
• Review ./docs/framework_divergences.md to understand how RSpade differs from standard Laravel

Getting Help

Run any command with --help to see detailed usage:

php artisan rsx:app:module:create --help

Use the man system for detailed documentation on specific topics:

php artisan rsx:man                    # List all topics
php artisan rsx:man routing            # View routing documentation
php artisan rsx:man jqhtml             # View jqhtml component documentation