102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
# WARP.md
|
|
|
|
This file provides guidance to WARP (warp.dev) when working with code in this repository.
|
|
|
|
Project summary: Laravel 12 backend with Vue 3 + Inertia.js (TypeScript) frontend, Vite build, Tailwind CSS 4, Pest for testing, Laravel Pint for PHP style. CI runs linting and tests on develop/main.
|
|
|
|
Common commands
|
|
|
|
- Initial setup
|
|
|
|
```bash path=null start=null
|
|
composer install
|
|
npm install
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
php artisan migrate
|
|
```
|
|
|
|
- Development servers
|
|
|
|
```bash path=null start=null
|
|
# Full stack (PHP server, queue listener, logs, Vite dev)
|
|
composer run dev
|
|
|
|
# Full stack with SSR renderer (builds SSR bundle, starts SSR service)
|
|
composer run dev:ssr
|
|
|
|
# Alternatively run pieces individually
|
|
npm run dev # Vite dev server
|
|
php artisan serve # Laravel HTTP server
|
|
php artisan queue:listen # Queue worker for async jobs
|
|
```
|
|
|
|
- Build assets
|
|
|
|
```bash path=null start=null
|
|
npm run build # Client bundle
|
|
npm run build:ssr # Client + SSR bundle
|
|
```
|
|
|
|
- Lint and format
|
|
|
|
```bash path=null start=null
|
|
# PHP code style (Laravel Pint)
|
|
vendor/bin/pint
|
|
|
|
# Frontend format (Prettier)
|
|
npm run format # write fixes
|
|
npm run format:check # check only
|
|
|
|
# Frontend lint (ESLint)
|
|
npm run lint # with --fix per eslint.config.js
|
|
```
|
|
|
|
- Tests (Pest)
|
|
|
|
```bash path=null start=null
|
|
# Run all tests
|
|
./vendor/bin/pest
|
|
|
|
# Run tests in a file or directory
|
|
./vendor/bin/pest tests/Feature/DashboardTest.php
|
|
|
|
# Filter by test name or pattern
|
|
./vendor/bin/pest --filter "authenticated users can visit the dashboard"
|
|
|
|
# Alternative (uses artisan test via composer)
|
|
composer run test
|
|
```
|
|
|
|
Architecture overview
|
|
|
|
- HTTP and routing
|
|
- routes/web.php defines the entry routes, rendering Inertia pages: Welcome and an auth-protected Dashboard. It includes routes/auth.php (auth flows) and routes/settings.php (Profile, Password, Appearance pages).
|
|
- Controllers live under app/Http/Controllers with Auth/* and Settings/* for user flows. ProfileController uses a typed FormRequest (ProfileUpdateRequest) for validation; PasswordController validates current_password and updates via Hash.
|
|
|
|
- Inertia + SSR integration
|
|
- Inertia middleware (app/Http/Middleware/HandleInertiaRequests.php) sets the root view to app and shares global props: app name, a random quote, the authenticated user, and sidebarOpen state derived from a cookie.
|
|
- SSR is enabled in config/inertia.php ('ssr.enabled' => true) and expects a renderer at http://127.0.0.1:13714. The SSR entry is resources/js/ssr.ts; use composer run dev:ssr or php artisan inertia:start-ssr after building the SSR bundle.
|
|
- The Blade root template resources/views/app.blade.php injects Vite assets and adds an inline theme bootstrap so dark mode applies before Vue mounts.
|
|
|
|
- Frontend structure (Vue 3 + TypeScript)
|
|
- Inertia app bootstrap is in resources/js/app.ts (resolvePageComponent to resources/js/pages/**/Name.vue). It sets document titles and a progress bar.
|
|
- Pages under resources/js/pages/ render into layouts in resources/js/layouts (for instance, AppLayout wraps AppShell). Global shell and sidebar behavior derive from $page.props shared by middleware.
|
|
- Composables (resources/js/composables) include useAppearance for light/dark theme initialization used on page load.
|
|
- UI components live under resources/js/components (with a shadcn-vue setup configured by components.json). TypeScript path alias @/* points to resources/js/* (see tsconfig.json).
|
|
|
|
- Build and tooling
|
|
- Vite config (vite.config.ts) wires laravel-vite-plugin, Tailwind CSS 4, Vue plugin, and @laravel/vite-plugin-wayfinder. Entry points: resources/js/app.ts (client) and resources/js/ssr.ts (SSR). Wayfinder provides typed route helpers for the frontend based on backend routes.
|
|
- Tailwind is configured for v4 with plugins; Prettier plugins include organize-imports and tailwindcss to keep classes ordered.
|
|
- ESLint (eslint.config.js) enables Vue + TypeScript rules and ignores vendor, node_modules, public, bootstrap/ssr, tailwind.config.js, and resources/js/components/ui/*.
|
|
|
|
- Data, auth, and testing
|
|
- Authentication uses the default 'web' session guard (config/auth.php). The User model (app/Models/User.php) uses hashed passwords and standard fillables. Email verification is supported via MustVerifyEmail checks in profile flows.
|
|
- phpunit.xml configures an in-memory SQLite database and testing environment variables, so tests run without external DB setup.
|
|
- Tests are written with Pest (tests/Feature, tests/Unit). tests/Pest.php binds Tests\TestCase and includes example expectations.
|
|
|
|
- CI signals (reference)
|
|
- .github/workflows/lint.yml runs Laravel Pint, Prettier format, and ESLint on develop/main branches.
|
|
- .github/workflows/tests.yml installs dependencies, builds assets, and runs Pest. Node 22 and PHP 8.4 are used in CI.
|
|
|