Docs: laravel / Design

Getting started

If you are already comfortable with Laravel, you can skim this section. Otherwise, follow the steps below to get the starter kit running locally.

First, extract the zip file, open the project folder in your terminal, and install the dependencies:

composer i && bun i

After the installation is complete, copy the example environment file and generate an application key:

cp .env.example .env
php artisan key:generate

Database setup

By default, this starter kit uses SQLite, so it works out of the box without any extra configuration.

If you prefer Postgres, update your .env file and set the appropriate values:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=your_database
DB_USERNAME=
DB_PASSWORD=

Replace your_database, DB_USERNAME, and DB_PASSWORD with your PostgreSQL credentials.

Then run the database migrations:

php artisan migrate

This project ships with roles and a user list. To quickly get an admin account and example users, run:

php artisan app:setup

The command will ask for your name, email, and password for the administrator account, then create 50 example users.

Serving the application

If you are using Herd, you can open the app by visiting your-project.test in your browser.

If you are using the built-in Laravel development server, run:

composer run dev

Email verification

Laravel ships with built in email verification. To enable it in this starter kit, you need to do two things.

First, mark your User model as MustVerifyEmail:

use Illuminate\Contracts\Auth\MustVerifyEmail;

class User extends Authenticatable implements MustVerifyEmail

Second, configure a mailer. For local development, you can use Mailpit. Install it on your machine, then add this to your .env file:

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="you@domain.com"
MAIL_FROM_NAME="${APP_NAME}"

Some of these values are null on purpose because Mailpit does not require authentication.

Run mailpit

Once your configuration is ready, start Mailpit from your terminal:

mailpit

If everything is set up correctly, you should see output similar to this:

INFO[2025/11/27 14:38:42] [smtpd] starting on [::]:1025 (no encryption)
INFO[2025/11/27 14:38:42] [http] starting on [::]:8025
INFO[2025/11/27 14:38:42] [http] accessible via http://localhost:8025/

Then open your browser and visit http://localhost:8025/ to access the Mailpit web interface and inspect outgoing emails.

Layout

This starter kit includes three layouts:

GuestLayout for unauthenticated pages
DashboardLayout for authenticated dashboard pages
AppLayout for public pages

If you do not need a dashboard layout, you can remove the DashboardLayout component and use AppLayout for all pages. For example, here is a profile page using DashboardLayout:

import DashboardLayout from "@/layouts/dashboard-layout"
import SettingsLayout from "@/layouts/settings-layout"

export default function Profile() {
  return (...)
}

Profile.layout = (page: React.ReactNode) => (
  <DashboardLayout breadcrumbs={breadcrumbs}>
    <SettingsLayout children={page} />
  </DashboardLayout>
)

To use AppLayout instead, change it to:

import AppLayout from "@/layouts/app-layout"
import SettingsLayout from "@/layouts/settings-layout"

export default function Profile() {
  return (...)
}

Profile.layout = (page: React.ReactNode) => (
  <AppLayout breadcrumbs={breadcrumbs}>
    <SettingsLayout children={page} />
  </AppLayout>
)

Quick login

To quickly test different users, you can visit a URL like http://localhost:8000/dev/login/5 to log in as the user with ID 5. Change the number at the end of the URL to log in as another user.

This feature is only available in the local environment. If you want to remove it, delete the routes/dev.php file and remove its require entry from routes/web.php.