laravel-vue-starter-kit — Nuxt 后台模板

SHA-256: d6ad04ee5c6b38b699f0eec5e8b5da051c03bc858725d44fa99c779294f8e7bf

2026-10-04T02:40:01.968Z

# Laravel Nuxt Starter Kit

[Leer en Español 🇪🇸](README.es.md)

[![Nuxt 3](https://img.shields.io/badge/Nuxt-3.x-00DC82?logo=nuxt&logoColor=white)](https://nuxt.com)
[![Laravel 13](https://img.shields.io/badge/Laravel-13.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com)
[![PHP 8.3+](https://img.shields.io/badge/PHP-8.3%2B-777BB4?logo=php&logoColor=white)](https://php.net)
[![Pnpm](https://img.shields.io/badge/Pnpm-9.x-F69220?logo=pnpm&logoColor=white)](https://pnpm.io)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

A production-ready full-stack boilerplate integrating a **Laravel 13 Headless REST API** backend with a modern **Nuxt 3 Dashboard** frontend. This starter kit provides a pre-configured architecture ideal for SaaS applications, admin panels, or complex web platforms.

---

## 📸 Screenshots

**Login**
![Login](.github/screenshots/login.png)

**Dashboard (Light)**
![Dashboard Light](.github/screenshots/dashboard-ligth.png)

**Dashboard (Dark)**
![Dashboard Dark](.github/screenshots/dashboard-black.png)

---

## Project Structure

This project is organized as a simple monorepo containing the following components:

```text
laravel-nuxt-starter-kit/
├── laravel-api-kit/     # Backend - Laravel 13 REST API (Headless Service)
└── nuxt-app-kit/        # Frontend - Nuxt 3 Admin Panel & Dashboard
```

---

## 🖥️ Frontend Features (Nuxt App Kit)

* **Nuxt 3 & Nuxt UI**: Modern user interface library powered by TailwindCSS and HeadlessUI elements.
* **Responsive Dashboard**: Collapsible sidebar, multi-column navigation, and optimized layouts.
* **Light/Dark Mode**: Built-in native support for color schemes.
* **Command Palette & Shortcuts**: Quick accessibility tools and keyboard navigation out-of-the-box.
* **Renovate Integration**: Configured for automated dependency updates.

---

## ⚙️ Backend Features (Laravel API Kit)

* **Strict Mode & Type Safety**: Enabled `declare(strict_types=1)`, `final` classes, type-hinting, strict equality, and PHPStan (Max Level).
* **Token Authentication**: Secure authentication via Laravel Sanctum.
* **Email Verification**: Built-in verification flow with signed URLs sent via email.
* **Password Reset**: Secure token-based password recovery.
* **API Versioning**: URI-based versioning (`/api/v1`) using `grazulex/laravel-apiroute` with sunset and deprecation header support.
* **Query Builder**: Dynamic filtering, sorting, and relationship loading using `spatie/laravel-query-builder`.
* **Data Transfer Objects (DTOs)**: Enforced type-safe API inputs/outputs via `spatie/laravel-data`.
* **Auto-Documentation**: Zero-annotation OpenAPI 3.1 schema and Swagger UI generation via `dedoc/scramble`.
* **Testing Suite**: Pest PHP configured for high-speed HTTP and unit testing.

---

## Setup & Installation

### 1. Backend Setup (`laravel-api-kit`)

Navigate to the backend directory:
```bash
cd laravel-api-kit
```

#### Option A: Docker (Recommended)
```bash
# Copy environment file
cp .env.example .env

# Build and start containers in the background
docker compose build
docker compose up -d

# Install Composer dependencies
docker compose run --rm app composer install

# Generate application key
docker compose run --rm app php artisan key:generate

# Run migrations
docker compose run --rm app php artisan migrate

# Verify installation with tests
docker compose run --rm app ./vendor/bin/pest
```

#### Option B: Local Setup (Without Docker)
Ensure you have PHP 8.3+ and Composer installed.
```bash
# Install dependencies
composer install

# Configure environment
cp .env.example .env
php artisan key:generate

# Setup local SQLite database
touch database/database.sqlite
php artisan migrate

# Run tests
./vendor/bin/pest

# Start local server
php artisan serve
```

Once running, access the auto-generated documentation:
* **Swagger UI**: [http://localhost:8080/docs/api](http://localhost:8080/docs/api)
* **OpenAPI Spec JSON**: [http://localhost:8080/docs/api.json](http://localhost:8080/docs/api.json)

---

### 2. Frontend Setup (`nuxt-app-kit`)

Navigate to the frontend directory:
```bash
cd ../nuxt-app-kit
```

```bash
# Copy environment variables
cp .env.example .env

# Install dependencies using pnpm
pnpm install

# Start the Nuxt development server
pnpm dev
```

Nuxt will be running locally at [http://localhost:3000](http://localhost:3000).

---

## Connecting Frontend & Backend

To sync the Nuxt frontend with the Laravel API, verify the cross-origin settings:

### Backend configuration (`laravel-api-kit/.env`)
Ensure stateful Sanctum requests are allowed from your frontend URL:
```env
SANCTUM_STATEFUL_DOMAINS=localhost:3000,127.0.0.1:3000
```

### Frontend configuration (`nuxt-app-kit/.env`)
Configure Nuxt's public base API URL to point to the Laravel endpoint:
```env
NUXT_PUBLIC_API_BASE=http://localhost:8080/api/v1
```

---

## Deep Dive: Backend Architecture & Usage

### API Endpoints (v1)

| Method | Endpoint | Auth | Description | Rate Limit |
|--------|----------|------|-------------|------------|
| `POST` | `/register` | No | Registers a new user account | 5 / min |
| `POST` | `/login` | No | Performs authentication and returns token | 5 / min |
| `POST` | `/logout` | Yes | Revokes current API token | 120 / min |
| `GET`  | `/me` | Yes | Retrieves authenticated user profile | 120 / min |
| `POST` | `/email/verify/{id}/{hash}` | Yes | Verifies user's email address | 120 / min |
| `POST` | `/email/resend` | Yes | Resends a verification email link | 6 / min |
| `POST` | `/forgot-password` | No | Sends password recovery email | 6 / min |
| `POST` | `/reset-password` | No | Updates password using recovery token | 6 / min |

### API Response Format

All responses from the Laravel API return a uniform JSON template:

* **Success (HTTP 200/201):**
  ```json
  {
    "success": true,
    "message": "Operation successful",
    "data": {
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]"
      }
    }
  }
  ```
* **Validation / Client Error (HTTP 422/400):**
  ```json
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "email": [
        "The email field must be a valid email address."
      ]
    }
  }
  ```

### Advanced Query Building

Using the Spatie Query Builder, you can filter, sort, and lazy-load relationships directly through URL parameters:

```php
// In a controller
$users = QueryBuilder::for(User::class)
    ->allowedFilters(['name', 'email'])
    ->allowedSorts(['name', 'created_at'])
    ->allowedIncludes(['posts'])
    ->paginate();
```

* **Filter by name:** `/api/v1/users?filter[name]=John`
* **Sort by creation date descending:** `/api/v1/users?sort=-created_at`
* **Include relationship data:** `/api/v1/users?include=posts`

### Rate Limiting

The application uses standard rate limiting rules configured in `AppServiceProvider.php`:
* `auth`: 5 requests per minute for login/register.
* `authenticated`: 120 requests per minute for logged-in sessions.
* `api`: 60 requests per minute for public endpoints.

---

## Development Commands

### Laravel API:
* **Lint codebase (Rector + Pint):** `composer lint` (Docker: `docker compose exec app composer lint`)
* **Static analysis & unit tests:** `composer test` (Docker: `docker compose exec app composer test`)
* **Reset Database:** `php artisan migrate:fresh --seed`

### Nuxt Frontend:
* **Production Build:** `pnpm build`
* **Preview production locally:** `pnpm preview`

---

## Credits

Special thanks to the original creators whose open-source repositories made this kit possible:

* **Laravel API Kit**: Developed by [grazulex](https://github.com/grazulex). Original Repository: [grazulex/laravel-api-kit](https://github.com/grazulex/laravel-api-kit).
* **Nuxt Dashboard Template**: Created by the [Nuxt Team](https://github.com/nuxt) as part of Nuxt UI templates. Original Repository: [nuxt-ui-templates/dashboard](https://github.com/nuxt-ui-templates/dashboard).