Setting Up a New Laravel Project the Right Way: Vite, Custom Templates & Git, Step by Step

ZerithonLabs Admin Getting Started Git Laravel Project Setup Templates Vite
Setting Up a New Laravel Project the Right Way: Vite, Custom Templates & Git, Step by Step

The first hour of a new Laravel project sets the tone for everything after it — get Vite configuration, template integration, and app config right, and every feature slots in smoothly afterward. This is the practical, step-by-step version: from composer create-project through setting the site identity, wiring Vite correctly, converting a raw HTML template into proper Blade layouts, and pushing a clean first commit to Git.

The first hour of a new Laravel project sets the tone for everything after it. Get the setup right — proper Vite configuration, a cleanly integrated template, correct app config — and every feature you build afterward slots in smoothly. Get it wrong, and you're fighting broken asset paths and messy Blade files for the life of the project. Here's the practical, step-by-step version.

Step 1: Create the Project

composer create-project laravel/laravel your-project-name
cd your-project-name

If you don't have Composer's Laravel installer set up globally, this works the same either way — composer create-project always pulls the latest stable Laravel release.

Verify it runs before touching anything else:

php artisan serve

Visit http://127.0.0.1:8000 — you should see the default Laravel welcome page.

Step 2: Set the Site Identity First

Before writing any feature code, configure the basics in .env:

APP_NAME="Your Site Name"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8000

Generate the app key (required — Laravel uses this for encryption):

php artisan key:generate

APP_NAME isn't cosmetic — it's used by default in the Blade starter templates ({{ config('app.name') }}), password reset emails, and notification subjects. Set it once now instead of finding "Laravel" in your password reset emails later.

Update config/app.php if you need anything beyond what .env covers (timezone, locale):

'timezone' => 'Asia/Dhaka',
'locale' => 'en',

Step 3: Database Connection

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=root
DB_PASSWORD=

Test the connection immediately by running the default migrations:

php artisan migrate

If this succeeds, your database config is correct before you've built a single feature on top of it.

Step 4: Vite Configuration

Laravel ships with Vite pre-wired, but the default setup assumes you're only compiling app.css and app.js. Open vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
            ],
            refresh: true,
        }),
    ],
});

refresh: true gives you auto-reload on Blade file changes during development — keep this on.

Install dependencies and start the dev server:

npm install
npm run dev

In your layout's <head>, load compiled assets with the @vite directive — never hardcode /css/app.css paths manually:

@vite(['resources/css/app.css', 'resources/js/app.js'])

For production, build once before deploying:

npm run build

This generates a public/build/ folder with hashed filenames — @vite automatically points to the correct hashed files in production, so cache-busting is handled for you with zero manual config.

Step 5: Integrating a Custom HTML Template

This is where most beginners create a mess — pasting raw template HTML into Blade files without adapting the asset pipeline. Do it properly instead.

5a. Place template assets correctly

If you bought or downloaded an HTML template with its own css/, js/, and images/ folders, don't leave them scattered. Move them into the Vite pipeline:

resources/
├── css/
│   └── app.css          ← import template CSS here
├── js/
│   └── app.js            ← import template JS here
└── template-assets/      ← template's own images, fonts, vendor libs
    ├── images/
    └── fonts/

In resources/css/app.css, import the template's stylesheet(s):

@import 'tailwindcss';
@import '../template-assets/css/template-style.css';

Or if the template isn't Tailwind-based, just import its raw CSS directly — Vite bundles it either way:

@import '../template-assets/css/style.css';
@import '../template-assets/css/responsive.css';

5b. Convert static HTML into Blade layout + sections

Take the template's index.html and split it into your layout structure instead of copy-pasting the whole file per page:

{{-- resources/views/layouts/app.blade.php --}}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>@yield('title', config('app.name'))</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    @include('partials._navbar')

    @yield('content')

    @include('partials._footer')
</body>
</html>
{{-- resources/views/home.blade.php --}}
@extends('layouts.app')

@section('title', 'Home')

@section('content')
    {{-- template's hero section markup goes here --}}
@endsection

5c. Fix asset references inside the template markup

Template HTML usually references images like <img src="images/hero.jpg">. Inside Blade, point these at the public path using asset():

<img src="{{ asset('template-assets/images/hero.jpg') }}" alt="Hero">

For most templates, simply copying the images/ and fonts/ folders into public/template-assets/ and referencing them with asset() is simpler and perfectly fine.

5d. Template JS that expects jQuery or plugins

Many templates assume jQuery/Bootstrap JS/AOS/Owl Carousel are globally available. Install what's actually needed via npm rather than loading external CDNs blindly:

npm install jquery bootstrap
// resources/js/app.js
import $ from 'jquery';
window.$ = window.jQuery = $;

import 'bootstrap';

Step 6: Git Setup and First Push

git init

Confirm .gitignore already excludes the essentials (Laravel's default one does, but verify):

/vendor
/node_modules
/public/build
/public/hot
.env
.env.backup
.phpunit.result.cache

Stage and commit:

git add .
git commit -m "Initial commit: Laravel project setup with Vite and custom template"

Connect to a remote (GitHub/GitLab) and push:

git remote add origin https://github.com/yourusername/your-project-name.git
git branch -M main
git push -u origin main

For every commit after this, keep messages specific rather than generic ("Add blog module with tags and pagination" beats "update").

Step 7: Final Sanity Checklist Before You Start Building Features

  • php artisan serve runs without errors
  • .env has correct APP_NAME, APP_URL, and database credentials
  • npm run dev compiles without errors and hot-reloads on Blade changes
  • Template assets load correctly with no 404s in browser dev tools (Network tab)
  • git status shows a clean working tree after your first commit
  • .env confirmed absent from git status output (never accidentally staged)

Quick Checklist

  • ✓ Project created and running locally before any customization
  • ✓ APP_NAME, APP_URL, timezone, and locale set deliberately, not left as defaults
  • ✓ Database connection verified via a real migration run
  • ✓ Vite configured with correct entry points, assets loaded only via @vite(), never hardcoded paths
  • ✓ Custom template converted into Blade layout + sections, not pasted as raw static HTML per page
  • ✓ Template JS dependencies installed via npm and imported, not loaded from random CDNs
  • ✓ .gitignore verified before the first commit, especially .env
  • ✓ First push done to a remote with a clear, descriptive commit message

Fifteen minutes spent getting these seven steps right up front saves hours of untangling broken asset paths and inconsistent config later in the project.