Development Vue
Daily workflow
| Command | What it does |
|---|---|
composer dev | Runs php artisan dev: Laravel server, queue listener, Pail logs and Vite together |
npm run dev | Vite dev server with HMR (also regenerates Wayfinder files) |
npm run build | Production build to public/build |
npm run build:ssr | Client and SSR bundle (vite build && vite build --ssr) |
npm run lint | eslint . + prettier --check resources/ + vue-tsc --noEmit |
npm run lint:fix | eslint . --fix + prettier --write resources/ + vue-tsc --noEmit |
composer lint | Pint, wayfinder:generate --with-form, typescript:transform, npm run lint:fix |
composer test | Lint check, PHPStan (Larastan), then php artisan test |
php artisan erag:generate-lang | Export lang/* to resources/js/lang/*.json |
The complete list is in Commands.
TIP
If a change isn't showing up in the browser, make sure npm run dev (or composer dev) is running, or run npm run build.
Adding a page
Let's say you want a Reports page in the Dashboard module, served at /reports. The request goes like this:
Modules/Dashboard/routes/web.php → ReportController@index
→ Inertia::render('reports/Index') → resources/js/pages/reports/Index.vue- Add the route to
Modules/Dashboard/routes/web.php, inside theauth+verifiedgroup, with->middleware('permission:View Reports|View Tenant Reports')and->name('reports.index'). - Create the controller at
Modules/Dashboard/Http/Controllers/ReportController.phpand have it returnInertia::render('reports/Index', [...]). Keep it thin; any business logic belongs inModules/<Module>/Services. - Create the page at
resources/js/pages/reports/Index.vue(the file is PascalCase, the folder lowercase). Breadcrumbs go indefineOptions({ layout: { breadcrumbs } }), and the title goes in<Head>. - Once Wayfinder has run, you can import
@/routes/reports.npm run devregenerates it for you; if that isn't running, usephp artisan wayfinder:generate --with-form. - Add the translation keys to
lang/<locale>/modules/dashboard.phpfor each locale, then runphp artisan erag:generate-lang. - Add
View Reportstoconfig/permissions/dashboard.phpandView Tenant Reportstoconfig/permissions/tenant/dashboard.php, then seed them. - If you want a menu item, add an entry to
database/seeders/MenuSeeder.php(anddatabase/seeders/tenant/MenuSeeder.php) with'route_name' => 'reports.index'and the permission. This step is optional.
The page itself doesn't need much:
<script setup lang="ts">
defineOptions({
layout: {
breadcrumbs: [{ title: 'modules.dashboard.reports.title', href: index() }],
},
});
defineProps<{ reports: { id: number; name: string }[] }>();
const { __ } = vueLang();
</script>View route and controller
// Modules/Dashboard/routes/web.php
use Modules\Dashboard\Http\Controllers\ReportController;
Route::middleware(['auth', 'verified'])->group(function () {
Route::get('reports', [ReportController::class, 'index'])
->middleware('permission:View Reports|View Tenant Reports')
->name('reports.index');
});// Modules/Dashboard/Http/Controllers/ReportController.php
namespace Modules\Dashboard\Http\Controllers;
use App\Http\Controllers\Controller;
use Inertia\Inertia;
use Inertia\Response;
class ReportController extends Controller
{
public function index(): Response
{
return Inertia::render('reports/Index', [
'reports' => [],
]);
}
}View full page
<script setup lang="ts">
import { vueLang } from '@erag/lang-sync-inertia/vue';
import { Head } from '@inertiajs/vue3';
import Heading from '@/components/Heading.vue';
import { dashboard } from '@/routes';
import { index } from '@/routes/reports';
defineOptions({
layout: {
breadcrumbs: [
{ title: 'modules.common.nav.dashboard', href: dashboard() },
{ title: 'modules.dashboard.reports.title', href: index() },
],
},
});
defineProps<{
reports: { id: number; name: string }[];
}>();
const { __ } = vueLang();
</script>
<template>
<Head :title="__('modules.dashboard.reports.title')" />
<div class="space-y-6 px-4 py-6">
<Heading
:title="__('modules.dashboard.reports.title')"
:description="__('modules.dashboard.reports.description')"
/>
</div>
</template>View translations, permissions and seeding
// lang/en/modules/dashboard.php (repeat for every locale)
'reports' => [
'title' => 'Reports',
'description' => 'Exported analytics reports.',
],// config/permissions/dashboard.php
[
'permission_name' => 'View Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],
// config/permissions/tenant/dashboard.php
[
'permission_name' => 'View Tenant Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],php artisan erag:generate-lang
php artisan db:seed --class=PermissionSeeder
php artisan tenants:seed --class="Database\Seeders\PermissionSeeder"
php artisan db:seed --class=MenuSeederAfter that, the keys work as __('modules.dashboard.reports.title') in Vue. In PHP you use the slash form: __('modules/dashboard.reports.title'). Menu titles are translated separately, from the nav.<slug> keys in lang/<locale>/modules/common.php.
Anyone who gets a system role from now on receives the permission through associated_roles. For users who already exist, grant it from Users → Assign permissions. To hide actions inside the page, use usePermission().can('View Reports', 'View Tenant Reports') (see Architecture → Permissions).
Roles and tenant seeding are covered in more depth in Users, roles & permissions.
View a feature test
use App\Models\User;
use Inertia\Testing\AssertableInertia as Assert;
use Spatie\Permission\Models\Permission;
test('users with the permission can visit the reports page', function () {
$user = User::factory()->create();
$user->givePermissionTo(Permission::findOrCreate('View Reports', 'web'));
$this->actingAs($user)
->get(route('reports.index'))
->assertInertia(fn (Assert $page) => $page->component('reports/Index'));
});php artisan test --compact --filter=reportsBecause testing.ensure_pages_exist is turned on in config/inertia.php, this test fails when reports/Index.vue doesn't exist.
Adding a form
A form posts to a controller through Inertia. If validation fails you get the messages back in errors; if it succeeds, the controller usually redirects with a flash toast.
<Form v-bind="store.form()"> → Controller (Form Request or Data class validates)
→ Service → Inertia::flash('toast', …) → redirect- On the backend, add a route and a controller action. Validate with a Form Request or a Data class (
UserController::storeusesUserData, for example), then call a service, flash a toast and redirect. - Import the Wayfinder function for the route:
import { store } from '@/routes/reports'. - Spread
store.form()into<Form>, and takeerrorsandprocessingfrom its slot. - Add the fields with
Common*components, giving each anameand:error. You don't needv-model.
<Form v-bind="store.form()" reset-on-success v-slot="{ errors, processing }">
<CommonInput name="name" :label="__('modules.dashboard.reports.name')" :error="errors.name" />
<CommonButton type="submit" :loading="processing">
{{ __('modules.common.actions.save_changes') }}
</CommonButton>
</Form>For edit forms, create/edit modals and useForm, head over to Inertia → Forms.
Type checking & linting
| Command | When |
|---|---|
npx vue-tsc --noEmit | Type check only |
npm run lint | Check ESLint, Prettier and types without changing files |
npm run lint:fix | Fix what can be fixed, then type check. Run before committing |
composer lint | Regenerate Wayfinder and TypeScript types, then run all PHP and frontend fixers |
ESLint wants import type for type-only imports, ordered imports, 1TBS braces and blank lines around control statements. The types for Data classes come from @/types/Modules/<Module>/Data, which php artisan typescript:transform generates.
WARNING
Until Wayfinder has generated @/routes and @/actions, vue-tsc will fail on those imports. Run npm run dev, npm run build or composer lint first.
Conventions
- Don't hard-code text. Every string the user sees goes through
__()with amodules.<feature>.<key>key, and that includes breadcrumbs, placeholders, toasts and confirm dialogs. - Don't write code comments; give things clear names instead (
.ai/rules/general.md). - Build fields and buttons with the
Common*components, and ask before destructive actions withuseConfirmDialog(). - Use Wayfinder rather than hard-coded URLs, and
.form()with<Form>. - Type everything. Take generated types from
@/types/Modules/...and useimport typefor type-only imports. - Put composables in
composables/useX.ts, and page-only components in that page'sPartials/folder.