Developer Customization Guide

Complete guide for developers to customize and extend PostUno

📖 Technology Stack
PostUno is built with modern technologies:

• ✅ Backend: Laravel 11 (PHP 8.2+)

• ✅ Frontend: React.js with Inertia.js

• ✅ Styling: Tailwind CSS 3.x

• ✅ Build Tool: Vite

• ✅ Database: MySQL 5.7+

• ✅ Package Manager: NPM & Composer

📁 Directory Structure

postuno/
├── app/                      # Laravel application logic
│   ├── Http/
│   │   ├── Controllers/      # All controllers
│   │   ├── Middleware/       # Custom middleware
│   │   └── Requests/         # Form requests
│   ├── Models/              # Eloquent models
│   └── Services/            # Business logic services
├── bootstrap/               # Laravel bootstrap files
├── config/                  # Application configuration
├── database/
│   ├── migrations/          # Database migrations
│   └── seeders/            # Database seeders
├── public/                  # Public accessible files
│   ├── assets/             # Static assets
│   └── build/              # Compiled assets
├── resources/
│   ├── js/                 # React components
│   │   ├── Components/     # Reusable components
│   │   ├── Pages/          # Page components
│   │   ├── Layouts/        # Layout templates
│   │   └── app.jsx         # Main app entry
│   ├── css/                # Stylesheets
│   │   └── app.css         # Main stylesheet
│   └── views/              # Blade templates
├── routes/
│   ├── web.php             # Web routes
│   ├── api.php             # API routes
│   └── installer.php       # Installation routes
├── storage/                # File storage
├── .env.example            # Environment example
├── composer.json           # PHP dependencies
├── package.json            # Node dependencies
├── tailwind.config.js      # Tailwind configuration
└── vite.config.js          # Vite configuration
                        

📝 Key Files to Know

File	         Purpose
.env	          Environment configuration (database, app settings)
resources/js/app.jsx	Main React application entry point
resources/css/app.css	Global styles and Tailwind imports
routes/web.php	    Application routes definition
tailwind.config.js	 Tailwind CSS customization

🚀 Development Environment Setup

Step 1: Install Dependencies

# Install PHP dependencies composer install # Install Node dependencies npm install

Step 2: Configure Environment

# Copy environment file cp .env.example .env # Generate application key php artisan key:generate # Configure database in .env file DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=postuno_dev DB_USERNAME=root DB_PASSWORD=

Step 3: Setup Database

# Run migrations php artisan migrate # Seed database (optional) php artisan db:seed

Step 4: Start Development Server

# Terminal 1: Start Laravel server php artisan serve # Terminal 2: Start Vite dev server (IMPORTANT!) npm run dev # Your app will be available at: # http://localhost:8000

🎨 Frontend Customization

1. Customizing Components

React components are located in resources/js/

// Example: Editing a page component // File: resources/js/Pages/Dashboard.jsx import React from 'react'; export default function Dashboard({ data }) { return ( <div className="p-6"> <h1 className="text-2xl font-bold">Dashboard</h1> {/* Your custom content */} </div> ); }

2. Customizing Styles

Global styles in resources/css/app.css

/* Add custom styles */ .custom-button { @apply px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600; } /* Override Tailwind variables */ :root { --primary-color: #3b82f6; --secondary-color: #10b981; }

3. Tailwind Configuration

Customize Tailwind in tailwind.config.js

module.exports = { content: [ './resources/**/*.{js,jsx,ts,tsx,vue}', ], theme: { extend: { colors: { primary: '#3b82f6', secondary: '#10b981', } } } }

🔧 Common Frontend Tasks

Adding a New Page

1. Create component in resources/js/Pages/YourPage.jsx

2. Add route in routes/web.php

3. Return Inertia response from controller
   

// Controller method public function yourPage() { return Inertia::render('YourPage', [ 'data' => $data ]); }

Adding a Reusable Component

// File: resources/js/Components/CustomButton.jsx export default function CustomButton({ children, onClick, variant = 'primary' }) { return ( <button onClick={onClick} className={`btn btn-${variant}`} > {children} </button> ); } // Usage in any page import CustomButton from '@/Components/CustomButton'; <CustomButton onClick={handleClick} variant="success"> Click Me </CustomButton>

⚙️ Backend Customization

1. Adding New Routes

Define routes in routes/web.php

// Basic route Route::get('/custom-page', [CustomController::class, 'index']) ->name('custom.index') ->middleware(['auth']); // Resource route Route::resource('items', ItemController::class) ->middleware(['auth']); // API route (routes/api.php) Route::apiResource('api/items', ApiItemController::class);

2. Creating Controllers

# Generate a controller php artisan make:controller CustomController # Generate a resource controller php artisan make:controller ItemController --resource

3. Working with Models

# Generate a model with migration php artisan make:model Item -m // Model example: app/Models/Item.php <?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Item extends Model { protected $fillable = ['name', 'description', 'status']; // Relationships public function user() { return $this->belongsTo(User::class); } }

4. Database Migrations

# Create migration php artisan make:migration create_items_table // Migration example public function up() { Schema::create('items', function (Blueprint $table) { $table->id(); $table->string('name'); $table->text('description')->nullable(); $table->enum('status', ['active', 'inactive']); $table->foreignId('user_id')->constrained(); $table->timestamps(); }); } # Run migration php artisan migrate

📦 Building for Production

Step 1: Build Frontend Assets

# Build optimized production assets npm run build # This creates optimized files in public/build/

Step 2: Optimize Laravel

# Clear and rebuild caches php artisan config:cache php artisan route:cache php artisan view:cache # Optimize autoloader composer install --optimize-autoloader --no-dev

Step 3: Environment Configuration

# Set production environment in .env APP_ENV=production APP_DEBUG=false APP_URL=https://yourdomain.com # Ensure proper permissions chmod -R 755 storage bootstrap/cache

🚀 Quick Commands Reference

Command	    Purpose
npm run dev:	     Start development server with hot reload
npm run build:	     Build for production
php artisan serve:	 Start Laravel development server
php artisan migrate:	 Run database migrations
php artisan cache:clear	 Clear all caches
php artisan queue:work	 Process queue jobs
composer update: 	     Update PHP dependencies
npm update: 	         Update Node dependencies