This repository demonstrates building a PWA for Laravel, Vite, Vue and TypeScript by configuring the vite-plugin-pwa.
Using vite-plugin-pwa in a Laravel project is made complex by Laravel being a mix of backend and frontend concepts. For example,
- Laravel has its own public dir inside the webserver's webroot. This means Vite builds to
/path/to/webroot/public/build/assets. This different to the usual frontend layout, where/build/assetswould be in the webroot. - There isn't a default static HTML entrypoint for the PWA. Laravel builds this server-side. The resulting HTML has a
<div id="app"></div>into which the Vue app is instantiated. - Laravel will put other things (like Telescope) in the public dir that you do not want offline.
- Laravel has its own plugin for Vite for builds, which adds an extra layer of configuration that vite-pwa does not normally encounter
To make it work, you need to configure vite-plugin-pwa to work around these issues:
- configure buildBase and outDir in vite.config.ts to make vite-pwa build to the same place as laravel/vite-plugin
- create a Blade file to act as an HTML entrypoint and add config for this to vite.config.ts
- Add a Service-Worker-Allowed header to your web server to work around the restrictions imposed by the build directory being in a subdir of the webroot
- Configuring caching in vite.config.ts to work around other assets being in the public dir that you do not want to be offline
There's a detailed GitHub issue exploring this problem here:
The accumulated knowledge within it lead to this Laravel, Vite, Vue3 and TypeScript app working as a PWA with offline support and app install prompts. The issue was asking for a demonstration repository so I created this repo to share it. Thoughts, feedback or improvements are welcome.
This repo demonstrates a working PWA with install prompts and offline support within Laravel using Vue3, Vite and Typescript. The useful things are:
- A vite.config.ts with settings for
vite-plugin-pwathat work with Laravel's directory layout - A Blade template that works as the entrypoint for the PWA
- A generator for the PWA icons
- A server.php file that supplies the sw.js and the Service-Worker-Allowed header for
php artisan servefor local development (see lines 18:23) - A composable usePwa that demonstrates how to access the
vite-plugin-pwafunctionality within Vue3 and TypeScript (eg install and update hooks, online/offline status) - A PwaStatus component that shows how it all works
- TypeScript types for the install event
This repo has been built on a vanilla install of Laravel 10 using composer from composer create-project laravel/laravel.
To add the PWA to your own Laravel project you can review the changes required to set up the PWA:
- Work through the commit history, which builds it up step-by-step
- Or view the entire diff of the HEAD against the vanilla Laravel install: https://github.com/sfreytag/laravel-vite-pwa/compare/a59497..HEAD
Or just fork the repo and start from there.
To build the repo, follow the usual Laravel steps. Nothing extra is required for vite-plugin-pwa. Assuming you have PHP, NPM and Composer:
git clone [email protected]:sfreytag/laravel-vite-pwa.git
cd laravel-vite-pwa
composer install
cp .env.example .env
php artisan key:generate
npm install
npm run build
Before you run it, bear in mind that the PWA installs a service worker and fills a cache. This can conflict with other service workers and caches from your other localhost projects. So it is recommended to use a port unique to each PWA project. To use eg 8082 for Laravel:
php artisan serve --port=8082
The app should now be running on http://localhost:8082. It should immediately work as a PWA. If you check the dev tools, the service worker should be running. If your browser supports it there will be an intall prompt in the address bar. It should then be installable. And if you use dev tools to take either the network or service worker offline, it should continue working if you reload the page.
The PWA is configured to only work with prod builds, rather than dev. This is straightforward to work with and helps stop the PWA cache get in the way of refreshing your build during the dev cycle. However this might not suit everyone. It would be a good PR to submit to this repo to get the PWA working with a dev build. In the meantime, before running the PWA and when making changes to be sure you have the latest version of it, ensure you use:
npm run build
This project uses @vite-pwa/assets-generator for its icons.
The canonical icon should be an SVG file. This is useful for the PWA anyway, so it can be saved in public/favicon.svg. Then build the other icons from it by running:
npm run pwa-icons
This generates a set of icons defined by the minimal preset described here.
They are automatically packaged in the public folder so they are web readable. They are also included in this repo so this process only needs repeating if you change the the canonical favicon.svg icon.
This screenshot demonstrates the useful features of vite-plugin-pwa within Laravel:
