入门套件

• 简介
• 使用入门套件创建应用
• 可用的入门套件
  • React
  • Svelte
  • Vue
  • Livewire
• 自定义入门套件
  • React
  • Svelte
  • Vue
  • Livewire
• 认证
  • 启用和禁用功能
  • 自定义用户创建与密码重置
  • 双因素认证
  • 频率限制
• 团队协作
• WorkOS AuthKit 认证
• Inertia SSR
• 社区维护的入门套件
• 常见问题解答

简介

为了助你更快地开启新的 Laravel 应用开发，我们很高兴地提供应用入门套件。这些入门套件为你构建下一个 Laravel 应用程序提供了良好的开端，并包含注册和认证应用用户所需的路由、控制器和视图。入门套件使用 Laravel Fortify 提供认证功能。

虽然我们欢迎你使用这些入门套件，但并非强制要求。你完全可以安装一份全新的 Laravel，从零开始构建自己的应用。无论如何，我们相信你一定能打造出出色的作品！

使用入门套件创建应用

要使用我们的某个入门套件创建新的 Laravel 应用，首先需要安装 PHP 和 Laravel CLI 工具。如果你已经安装了 PHP 和 Composer，可以通过 Composer 安装 Laravel CLI 安装器工具：

composer global require laravel/installer

Trace92 翻译于 4天前

0 重译

然后，使用 Laravel CLI 安装器创建一个新的 Laravel 应用。Laravel 安装器会提示你选择喜欢的入门套件：

laravel new my-app

创建完 Laravel 应用后，你只需通过 NPM 安装前端依赖，并启动 Laravel 开发服务器：

cd my-app
npm install && npm run build
composer run dev

启动 Laravel 开发服务器后，你的应用便可以在浏览器中通过 localhost:8000 访问。

可用的入门套件

React

我们的 React 入门套件为使用 Inertia 构建 React 前端的 Laravel 应用提供了一个健壮且现代的起点。

Inertia 让你能够使用经典的服务端路由和控制器来构建现代化的单页 React 应用。这使你既能享受 React 的前端强大能力，又能结合 Laravel 惊人的后端开发效率以及极速的 Vite 编译体验。

React 入门套件采用了 React 19、TypeScript、Tailwind 以及 shadcn/ui 组件库。

Svelte

我们的 Svelte 入门套件为使用 Inertia 构建 Svelte 前端的 Laravel 应用提供了一个健壮且现代的起点。

Inertia 让你能够使用经典的服务端路由和控制器来构建现代化的单页 Svelte 应用。这使你既能享受 Svelte 的前端强大能力，又能结合 Laravel 惊人的后端开发效率以及极速的 Vite 编译体验。

Svelte 入门套件采用了 Svelte 5、TypeScript、Tailwind 以及 shadcn-svelte 组件库。

Trace92 翻译于 4天前

0 重译

Vue

我们的 Vue 入门套件为使用 Inertia 构建 Vue 前端的 Laravel 应用提供了一个出色的起点。

Inertia 让你能够使用经典的服务端路由和控制器来构建现代化的单页 Vue 应用。这使你既能享受 Vue 的前端强大能力，又能结合 Laravel 惊人的后端开发效率以及极速的 Vite 编译体验。

Vue 入门套件采用了 Vue 组合式 API、TypeScript、Tailwind 以及 shadcn-vue 组件库。

Livewire

我们的 Livewire 入门套件为使用 Laravel Livewire 构建前端的 Laravel 应用提供了完美的起点。

Livewire 是一种仅用 PHP 构建动态、响应式前端 UI 的强大方式。它非常适合主要使用 Blade 模板的团队，且希望寻找一种比 React、Svelte 和 Vue 等 JavaScript 驱动的 SPA 框架更简单的替代方案。

Livewire 入门套件采用了 Livewire、Tailwind 以及 Flux UI 组件库。

自定义入门套件

React

我们的 React 入门套件基于 Inertia 3、React 19、Tailwind 4 和 shadcn/ui 构建。与所有入门套件一样，后端和前端代码全部位于你的应用中，以便完全自定义。

前端代码主要位于 resources/js 目录中。你可以自由修改任何代码，以自定义应用的外观和行为：

resources/js/
├── components/    # 可复用的 React 组件
├── hooks/         # React 钩子函数
├── layouts/       # 应用布局
├── lib/           # 工具函数和配置
├── pages/         # 页面组件
└── types/         # TypeScript 类型定义

Trace92 翻译于 4天前

0 重译

要发布额外的 shadcn 组件，首先 找到你想要发布的组件。然后，使用 npx 发布该组件：

npx shadcn@latest add switch

在这个示例中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch.tsx。组件发布后，你就可以在任何页面中使用它：

import { Switch } from "@/components/ui/switch"

const MyPage = () => {
  return (
    <div>
      <Switch />
    </div>
  );
};

export default MyPage;

可用的布局

React 入门套件包含两种不同的主要布局供你选择：一种「侧边栏」布局和一种「顶部导航」布局。默认使用侧边栏布局，但你可以通过修改应用 resources/js/layouts/app-layout.tsx 文件顶部导入的布局来切换为顶部导航布局：

import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout'; // [tl! remove]
import AppLayoutTemplate from '@/layouts/app/app-header-layout'; // [tl! add]

侧边栏变体

侧边栏布局包含三种不同的变体：默认侧边栏变体、「嵌入」变体和「浮动」变体。你可以通过修改 resources/js/components/app-sidebar.tsx 组件来选择最喜欢的变体：

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

认证页面布局变体

React 入门套件包含的认证页面（如登录页面和注册页面）同样提供三种不同的布局变体：「简约」、「卡片」和「分栏」。

要更改认证布局，修改应用 resources/js/layouts/auth-layout.tsx 文件顶部导入的布局即可：

import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout'; // [tl! remove]
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout'; // [tl! add]

Trace92 翻译于 4天前

0 重译

Svelte

我们的 Svelte 入门套件基于 Inertia 3、Svelte 5、Tailwind 和 shadcn-svelte 构建。与我们所有的入门套件一样，所有的后端和前端代码都存在于你的应用程序中，以实现完全自定义。

前端代码主要位于 resources/js 目录中。你可以自由修改任何代码，以自定义应用的外观和行为：

resources/js/
├── components/ # 可复用的 Svelte 组件
├── layouts/ # 应用布局
├── lib/ # 工具函数、配置及 Svelte rune 模块
├── pages/ # 页面组件
└── types/ # TypeScript 类型定义

要发布更多 shadcn-svelte 组件，首先找到你想要发布的组件，然后使用 npx 命令进行发布：

npx shadcn-svelte@latest add switch

在这个示例中，该命令会将 Switch 组件发布到 resources/js/components/ui/switch/switch.svelte。组件发布后，你就可以在任何页面中使用它：

<script lang="ts">
    import { Switch } from '@/components/ui/switch'
</script>

<div>
    <Switch />
</div>

可用的布局

Svelte 入门套件包含两种不同的主要布局供你选择：一种「侧边栏」布局和一种「顶部导航」布局。默认使用侧边栏布局，但你可以通过修改应用 resources/js/layouts/AppLayout.svelte 文件顶部导入的布局来切换为顶部导航布局：

import AppLayout from '@/layouts/app/AppSidebarLayout.svelte'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.svelte'; // [tl! add]

Trace92 翻译于 4天前

0 重译

Sidebar Variants

The sidebar layout includes three different variants: the default sidebar variant, the "inset" variant, and the "floating" variant. You may choose the variant you like best by modifying the resources/js/components/AppSidebar.svelte component:

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

Authentication Page Layout Variants

The authentication pages included with the Svelte starter kit, such as the login page and registration page, also offer three different layout variants: "simple", "card", and "split".

To change your authentication layout, modify the layout that is imported at the top of your application's resources/js/layouts/AuthLayout.svelte file:

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte'; // [tl! remove]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte'; // [tl! add]

Vue

Our Vue starter kit is built with Inertia 3, Vue 3 Composition API, Tailwind, and shadcn-vue. As with all of our starter kits, all of the backend and frontend code exists within your application to allow for full customization.

The majority of the frontend code is located in the resources/js directory. You are free to modify any of the code to customize the appearance and behavior of your application:

resources/js/
├── components/    # Reusable Vue components
├── composables/   # Vue composables / hooks
├── layouts/       # Application layouts
├── lib/           # Utility functions and configuration
├── pages/         # Page components
└── types/         # TypeScript definitions

To publish additional shadcn-vue components, first find the component you want to publish. Then, publish the component using npx:

npx shadcn-vue@latest add switch

In this example, the command will publish the Switch component to resources/js/components/ui/Switch.vue. Once the component has been published, you can use it in any of your pages:

<script setup lang="ts">
import { Switch } from '@/components/ui/switch'
</script>

<template>
    <div>
        <Switch />
    </div>
</template>

Available Layouts

The Vue starter kit includes two different primary layouts for you to choose from: a "sidebar" layout and a "header" layout. The sidebar layout is the default, but you can switch to the header layout by modifying the layout that is imported at the top of your application's resources/js/layouts/AppLayout.vue file:

import AppLayout from '@/layouts/app/AppSidebarLayout.vue'; // [tl! remove]
import AppLayout from '@/layouts/app/AppHeaderLayout.vue'; // [tl! add]

Sidebar Variants

The sidebar layout includes three different variants: the default sidebar variant, the "inset" variant, and the "floating" variant. You may choose the variant you like best by modifying the resources/js/components/AppSidebar.vue component:

<Sidebar collapsible="icon" variant="sidebar"> [tl! remove]
<Sidebar collapsible="icon" variant="inset"> [tl! add]

Authentication Page Layout Variants

The authentication pages included with the Vue starter kit, such as the login page and registration page, also offer three different layout variants: "simple", "card", and "split".

To change your authentication layout, modify the layout that is imported at the top of your application's resources/js/layouts/AuthLayout.vue file:

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue'; // [tl! remove]
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue'; // [tl! add]

Livewire

Our Livewire starter kit is built with Livewire 4, Tailwind, and Flux UI. As with all of our starter kits, all of the backend and frontend code exists within your application to allow for full customization.

The majority of the frontend code is located in the resources/views directory. You are free to modify any of the code to customize the appearance and behavior of your application:

resources/views
├── components            # Reusable components
├── flux                  # Customized Flux components
├── layouts               # Application layouts
├── pages                 # Livewire pages
├── partials              # Reusable Blade partials
├── dashboard.blade.php   # Authenticated user dashboard
├── welcome.blade.php     # Guest user welcome page

Available Layouts

The Livewire starter kit includes two different primary layouts for you to choose from: a "sidebar" layout and a "header" layout. The sidebar layout is the default, but you can switch to the header layout by modifying the layout that is used by your application's resources/views/layouts/app.blade.php file. In addition, you should add the container attribute to the main Flux component:

<x-layouts::app.header>
    <flux:main container>
        {{ $slot }}
    </flux:main>
</x-layouts::app.header>

Authentication Page Layout Variants

The authentication pages included with the Livewire starter kit, such as the login page and registration page, also offer three different layout variants: "simple", "card", and "split".

To change your authentication layout, modify the layout that is used by your application's resources/views/layouts/auth.blade.php file:

<x-layouts::auth.split>
    {{ $slot }}
</x-layouts::auth.split>

Authentication

All starter kits use Laravel Fortify to handle authentication. Fortify provides routes, controllers, and logic for login, registration, password reset, email verification, and more.

Fortify automatically registers the following authentication routes based on the features that are enabled in your application's config/fortify.php configuration file:

The php artisan route:list Artisan command can be used to display all of the routes in your application.

Enabling and Disabling Features

You can control which Fortify features are enabled in your application's config/fortify.php configuration file:

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::twoFactorAuthentication([
        'confirm' => true,
        'confirmPassword' => true,
    ]),
],

To disable a feature, comment out or remove that feature entry from the features array. For example, remove Features::registration() to disable public registration.

When using the React, Svelte or Vue starter kits, you will also need to remove any references to the disabled feature's routes in your frontend code. For example, if you disable email verification, you should remove the imports and references to the verification routes in your React, Svelte, or Vue components. This is necessary because these starter kits use Wayfinder for type-safe routing, which generates route definitions at build time. If you reference routes that no longer exist, your application will fail to build.

Customizing User Creation and Password Reset

When a user registers or resets their password, Fortify invokes action classes located in your application's app/Actions/Fortify directory:

For example, to customize your application's registration logic, you should edit the CreateNewUser action:

public function create(array $input): User
{
    Validator::make($input, [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email', 'max:255', 'unique:users'],
        'phone' => ['required', 'string', 'max:20'], // [tl! add]
        'password' => $this->passwordRules(),
    ])->validate();

    return User::create([
        'name' => $input['name'],
        'email' => $input['email'],
        'phone' => $input['phone'], // [tl! add]
        'password' => Hash::make($input['password']),
    ]);
}

Two-Factor Authentication

Starter kits include built-in two-factor authentication (2FA), allowing users to secure their accounts using any TOTP-compatible authenticator app. 2FA is enabled by default via Features::twoFactorAuthentication() in your application's config/fortify.php configuration file.

The confirm option requires users to verify a code before 2FA is fully enabled, while confirmPassword requires password confirmation before enabling or disabling 2FA. For more details, see Fortify's two-factor authentication documentation.

Rate Limiting

Rate limiting prevents brute-forcing and repeated login attempts from overwhelming your authentication endpoints. You can customize Fortify's rate limiting behavior in your application's FortifyServiceProvider:

use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Cache\RateLimiting\Limit;

RateLimiter::for('login', function ($request) {
    return Limit::perMinute(5)->by($request->email.$request->ip());
});

Teams

The React, Svelte, Vue, and Livewire starter kits may also be generated with team support. When the teams feature is enabled, each user belongs to one or more teams and has a current team. During registration, new users are automatically given a personal team. The starter kits also include team management screens for creating teams, switching between teams, inviting members, and updating team details.

When a route is scoped to the current team, the current team's slug is included in the URL. For example, the dashboard route becomes /{current_team}/dashboard, while team management pages use routes such as settings/teams/{team}. When using the {current_team} and {team} route parameters, the starter kits automatically ensure that the authenticated user belongs to the requested team before allowing access to the route.

To make generating team-aware URLs more convenient, the starter kits register URL defaults for the authenticated user's current team. This allows calls to helpers such as route('dashboard') to automatically include the current team's slug. When a user signs in, registers, or switches teams, the starter kits update the current team and refresh these URL defaults so generated links continue to use the correct team context.

When creating or renaming a team, the starter kits also prevent users from choosing reserved names that could produce unsafe or conflicting route segments. For example, names that would collide with route prefixes such as settings, login, or dashboard may not be used.

WorkOS AuthKit Authentication

By default, the React, Svelte, Vue, and Livewire starter kits all utilize Laravel's built-in authentication system to offer login, registration, password reset, email verification, and more. In addition, we also offer a WorkOS AuthKit powered variant of each starter kit that offers:

Using WorkOS as your authentication provider requires a WorkOS account. WorkOS offers free authentication for applications up to 1 million monthly active users.

To use WorkOS AuthKit as your application's authentication provider, select the WorkOS option when creating your new starter kit powered application via laravel new.

Configuring Your WorkOS Starter Kit

After creating a new application using a WorkOS powered starter kit, you should set the WORKOS_CLIENT_ID, WORKOS_API_KEY, and WORKOS_REDIRECT_URL environment variables in your application's .env file. These variables should match the values provided to you in the WorkOS dashboard for your application:

WORKOS_CLIENT_ID=your-client-id
WORKOS_API_KEY=your-api-key
WORKOS_REDIRECT_URL="${APP_URL}/authenticate"

Additionally, you should configure the application homepage URL in your WorkOS dashboard. This URL is where users will be redirected after they log out of your application.

Configuring AuthKit Authentication Methods

When using a WorkOS powered starter kit, we recommend that you disable "Email + Password" authentication within your application's WorkOS AuthKit configuration settings, allowing users to only authenticate via social authentication providers, passkeys, "Magic Auth", and SSO. This allows your application to totally avoid handling user passwords.

Configuring AuthKit Session Timeouts

In addition, we recommend that you configure your WorkOS AuthKit session inactivity timeout to match your Laravel application's configured session timeout threshold, which is typically two hours.

Inertia SSR

The React, Svelte, and Vue starter kits are compatible with Inertia's server-side rendering capabilities. To build an Inertia SSR compatible bundle for your application, run the build:ssr command:

npm run build:ssr

For convenience, a composer dev:ssr command is also available. This command will start the Laravel development server and Inertia SSR server after building an SSR compatible bundle for your application, allowing you to test your application locally using Inertia's server-side rendering engine:

composer dev:ssr

Community Maintained Starter Kits

When creating a new Laravel application using the Laravel installer, you may provide any community maintained starter kit available on Packagist to the --using flag:

laravel new my-app --using=example/starter-kit

Creating Starter Kits

To ensure your starter kit is available to others, you will need to publish it to Packagist. Your starter kit should define its required environment variables in its .env.example file, and any necessary post-installation commands should be listed in the post-create-project-cmd array of the starter kit's composer.json file.

Frequently Asked Questions

How do I upgrade?

Every starter kit gives you a solid starting point for your next application. With full ownership of the code, you can tweak, customize, and build your application exactly as you envision. However, there is no need to update the starter kit itself.

How do I enable email verification?

Email verification can be added by uncommenting the MustVerifyEmail import in your App/Models/User.php model and ensuring the model implements the MustVerifyEmail interface:

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
// ...

class User extends Authenticatable implements MustVerifyEmail
{
    // ...
}

After registration, users will receive a verification email. To restrict access to certain routes until the user's email address is verified, add the verified middleware to the routes:

Route::middleware(['auth', 'verified'])->group(function () {
    Route::get('dashboard', function () {
        return Inertia::render('dashboard');
    })->name('dashboard');
});

[!NOTE]
Email verification is not required when using the WorkOS variant of the starter kits.

How do I modify the default email template?

You may want to customize the default email template to better align with your application's branding. To modify this template, you should publish the email views to your application with the following command:

php artisan vendor:publish --tag=laravel-mail

This will generate several files in resources/views/vendor/mail. You can modify any of these files as well as the resources/views/vendor/mail/themes/default.css file to change the look and appearance of the default email template.