If you've ever deployed a Laravel application only to be greeted by a blank page, missing CSS, or JavaScript that mysteriously stopped working, you're not alone.
One of the most common production issues in modern Laravel applications is Vite assets failing after deployment. The application itself appears healthy—the routes respond correctly, the database connection works, and authentication is functional—but the frontend is completely broken.
Typical symptoms include:
-
CSS is missing.
-
JavaScript never loads.
-
Images disappear.
-
The browser returns 404 for assets.
-
Laravel throws a Vite manifest not found exception.
-
Everything worked perfectly on your local machine.
These issues are rarely caused by Vite itself. More often, they're the result of deployment workflows, incorrect build processes, configuration mistakes, or server environment differences.
In this guide, we'll walk through the most common causes of Laravel Vite deployment failures, explain why they happen, and show you how to resolve them using a production-focused debugging approach.
Understanding How Laravel Vite Works
Before troubleshooting, it's important to understand the deployment flow.
During development:
Browser
│
▼
Laravel
│
▼
Vite Development Server
│
▼
Hot Module Reloading (HMR)
During production:
Developer
↓
npm run build
↓
public/build/
↓
manifest.json
↓
Laravel
↓
Browser
Notice the difference.
Production does not use the Vite development server.
Instead, Laravel reads the generated manifest.json file inside:
public/build/
If that folder or manifest is missing, Laravel cannot locate your compiled assets.
Problem 1: "Vite Manifest Not Found"
This is probably the most searched Laravel Vite deployment error.
Example:
Vite manifest not found at:
public/build/manifest.json
Why it happens
The production server never generated the assets.
Many developers upload their Laravel project without running:
npm install
npm run build
As a result:
public/build/
doesn't exist.
Solution
Generate production assets before deployment.
npm install
npm run build
You should now have:
public/
build/
assets/
manifest.json
Deploy this folder together with your application.
Problem 2: Assets Return 404
Another common issue:
GET
/build/assets/app-xxxxx.js
404 Not Found
Possible causes
-
build folder not uploaded
-
wrong document root
-
symbolic link issues
-
deployment script ignored build directory
Verify:
public/build/
actually exists on production.
Problem 3: Forgot to Run npm run build
This sounds obvious.
Yet it's probably responsible for thousands of deployment failures every month.
Development uses
npm run dev
Production requires
npm run build
Never deploy after only running
npm run dev
Problem 4: Wrong APP_URL
Many asset URLs are generated using
APP_URL
Example
APP_URL=http://localhost
If production still contains
localhost
your generated asset URLs may point to an invalid host.
Always verify
APP_URL=https://example.com
Then clear configuration cache.
php artisan optimize:clear
Problem 5: Configuration Cache
Laravel caches configuration aggressively.
Even after updating:
.env
Laravel may still use the old configuration.
Run:
php artisan optimize:clear
php artisan config:cache
This eliminates many mysterious deployment issues.
Problem 6: Browser Cache
Sometimes nothing is actually broken.
Your browser simply cached the previous assets.
Because Vite generates hashed filenames like
app.4df87ab.js
old cached HTML may reference files that no longer exist.
Try:
-
Hard refresh
-
Incognito mode
-
Clear browser cache
Problem 7: Node Modules Missing on Server
If your deployment builds assets directly on the server:
npm run build
Node.js must be installed.
Check:
node -v
npm -v
If either command fails, the build cannot complete.
Many shared hosting environments do not support Node.js.
In those cases, build assets locally or through CI/CD before uploading.
Problem 8: Git Ignored the Build Directory
Developers often add:
public/build
to
.gitignore
Then wonder why production lacks assets.
If your deployment relies on Git alone, ensure your workflow either:
-
commits built assets when appropriate, or
-
rebuilds them during deployment.
Problem 9: Incorrect Permissions
Sometimes assets exist but cannot be read.
Verify permissions:
chmod -R 755 public/build
chown -R www-data:www-data public/build
(Adjust the user for your server.)
Problem 10: Deployment Pipeline Didn't Build Assets
Modern deployments often use GitHub Actions, GitLab CI, or other CI/CD platforms.
A common mistake is deploying only PHP dependencies:
composer install
without:
npm install
npm run build
Your deployment pipeline should include both PHP and frontend build steps.
Problem 11: Mixed Content Errors
If your application serves HTTPS but assets are requested over HTTP, browsers block them.
Example:
https://example.com
↓
http://example.com/build/app.js
Open Developer Tools → Console to check for mixed-content warnings.
Ensure APP_URL uses https:// and your web server is configured correctly.
Problem 12: Incorrect Web Server Configuration
Whether you use Nginx, Apache, or a control panel like cPanel, your web server must point the document root to Laravel's public directory.
If the document root points to the project root instead, asset paths can fail, and your application may expose sensitive files.
Verify your virtual host or server block is configured to serve from:
/path-to-project/public
A Production Deployment Checklist
Before every deployment, verify the following:
-
✅ Run
composer install --no-dev --optimize-autoloader -
✅ Run
npm install -
✅ Run
npm run build -
✅ Confirm
public/build/manifest.jsonexists -
✅ Set the correct
APP_URL -
✅ Clear Laravel caches with
php artisan optimize:clear -
✅ Rebuild the configuration cache if needed
-
✅ Ensure the web server points to the
publicdirectory -
✅ Verify
public/buildhas the correct permissions -
✅ Test the application in an incognito browser window
Following this checklist dramatically reduces deployment-related asset issues.
Frequently Asked Questions
Why does Laravel Vite work locally but fail after deployment?
Local development uses the Vite development server with hot module replacement, while production serves compiled assets from the public/build directory. If those assets were never built or uploaded, the application cannot load them.
Do I need Node.js on my production server?
Not necessarily. If your CI/CD pipeline or local machine builds the assets before deployment, Node.js isn't required on the production server. If you build directly on the server, Node.js and npm must be available.
Can I ignore the public/build folder in Git?
You can, but only if your deployment process reliably runs npm install and npm run build. Otherwise, the application will be missing its compiled assets.
Should I use npm run dev in production?
No. npm run dev starts the development server. Production deployments should always use npm run build.
Final Thoughts
Most Laravel Vite deployment problems aren't caused by Vite itself—they're caused by missing build steps, configuration drift, or deployment workflows that differ from local development.
When troubleshooting, start with the basics:
-
Confirm the assets were built.
-
Verify
public/build/manifest.jsonexists. -
Check your
APP_URL. -
Clear Laravel caches.
-
Inspect browser network requests and server logs.
Approaching the problem systematically will resolve the vast majority of production asset issues.
What's Next?
In the next article in this Laravel Production Engineering series, we'll cover:
Docker for Laravel Developers: Complete Beginner Guide
We'll explore how Docker helps create consistent development and deployment environments, reducing the "works on my machine" problems that often lead to production issues.
