Vite.js Next Generation Frontend Tooling + Craft CMS

Vite.js is next gen­er­a­tion fron­tend tool­ing that can replace web­pack, Mix, Gulp, etc. for build­ing fron­tend assets like JavaScript and CSS.

In this arti­cle, we’ll explore how you can lever­age Vite.js as a fast, sim­ple build sys­tem for your Craft CMS websites.

Vite.js is a fast & opinionated… but its opinions are quite good

Vite.js is designed to work with the JavaScript & Node.js ecosys­tems, but using the Vite plu­g­in I wrote, we can use it for Craft CMS too.

Vite.js has fast start­up times because it lever­ages ES Mod­ules in mod­ern browsers rather than bundling, and it uses esbuild under the hood for fast tran­spi­la­tion of Type­Script, JSX, and more.

If you want to try out a live, ful­ly func­tion­ing web­site your­self that uses Vite.js, check out the Spoke & Chain GitHub repos­i­to­ry. Com­pare & con­trast this with the Europa Muse­um GitHub repos­ti­to­ry, which has the same archi­tec­ture, but uses web­pack 5 for the buildchain.

Link Why Vite.js?

The pri­ma­ry rea­sons to use Vite.js are speed and simplicity.

It’s fast to start up, the hot mod­ule replace­ment (HMR) is near-instan­ta­neous, and the pro­duc­tion build times are fast too.

It’s also quite sim­ple to set up, there isn’t much con­fig­u­ra­tion to be done, and using it involves just link­ing to the script you want to use.

Vite.js combines the simplicity of a script tag with the power of modern JavaScript

Instead of set­ting up an elab­o­rate Babel pipeline, you just put a <script src="src/js/app.ts"> in your code, and like mag­ic you can use TypeScript.

While it is tough to pre­dict future trends, Vite.js also seems to be trend­ing in the right direc­tion rel­a­tive­ly to the new crop of bundling tools.

Link Configuring the Vite plugin for Craft CMS

Vite.js is JavaScript fron­tend tool­ing, so by default it uses an index.html as an entry­point to your appli­ca­tion.

That does­n’t make sense in the con­text of a serv­er-ren­dered set­up like Craft CMS, but with the Vite plu­g­in and some minor con­fig­u­ra­tion changes, it works like a charm.

The first step is to install the plugin:

You can also install the plu­g­in via the Plu­g­in Store in the Craft CP as well.

Next we need to copy the file config.php from vendor/nystudio107/craft-vite/src/ to the Craft config/ direc­to­ry as vite.php (so rename the file in the process).

Here’s what the file will look like:

You’ll need to make a few changes to this file depend­ing on what your local devel­op­ment envi­ron­ment looks like.

These are the set­tings you’ll need to change for your project:

• useDevServer — is a boolean that sets whether you will be using Vite dev serv­er for hot mod­ule replace­ment (HMR). This defaults to using the DEV_MODE envi­ron­ment vari­able, so it’ll be on when in dev­Mode, and off when not.
• manifestPath — the pub­lic serv­er path to your man­i­fest files; it can be a full URL or a par­tial path, or a Yii2 alias. This is usu­al­ly the same as what­ev­er you set your build.outDir to in vite.config.js
• devServerPublic — the URL to the Vite dev serv­er, which is used for the hot mod­ule replace­ment (HMR); it can be a full URL or a par­tial path, or a Yii2 alias. Usu­al­ly this is http://localhost:3000, since Vite defaults to that. This will appear in <script> tags on the fron­tend when the dev serv­er is running
• serverPublic — the pub­lic serv­er URL to your asset files; it can be a full URL or a par­tial path, or a Yii2 alias. This will appear in <script> tags on the fron­tend for pro­duc­tion builds. App::env('PRIMARY_SITE_URL') . '/dist/' is a typ­i­cal setting

• errorEntry — is a string, or array of strings, that should be the JavaScript entry point(s) (e.g.: src/js/app.js) that should be inject­ed into Twig error tem­plates, to allow hot mod­ule replace­ment to work through Twig error pages. devMode must be true and useDevServer must also be true for this to have any effect.
• cacheKeySuffix — String to be append­ed to the cache key
• devServerInternal — The inter­nal URL to the dev serv­er, when accessed from the envi­ron­ment in which PHP is exe­cut­ing. This can be the same as devServerPublic, but may be dif­fer­ent in con­tainer­ized or VM setups. ONLY used if checkDevServer = true
• checkDevServer — Should we check for the pres­ence of the dev serv­er by ping­ing devServerInternal to make sure it’s running?

See the Vite doc­u­men­ta­tion if you need more help set­ting this up for your local dev environment.

Link Vite.js configuration

Next we need to set up Vite.js itself. First you’ll need a package.json that might look some­thing like this:

These are the pack­ages you’ll need to set up a bare-bones Vite.js set­up that works with Tail­wind CSS. If you want to use Vue.js or React or Svelte or some oth­er fron­tend frame­work, you’ll just add those pack­ages and the appro­pri­ate Vite.js plu­g­ins.

Then do an npm install to install your pack­ages, and then gen­er­ate default tailwind.config.js and postcss.config.js files with:

Next we’ll cre­ate a vite.config.js file for our Vite.js configuration:

The @vitejs/plugin-legacy plu­g­in gen­er­ates a lega­cy bun­dle for non-ESM native browsers, and the Vite plu­g­in takes care of gen­er­at­ing the appro­pri­ate module/​nomodule tags for you.

The vite-plu­g­in-restart plu­g­in allows us to get live reload for our Twig tem­plates or oth­er files, in addi­tion to the out of the box HMR for JavaScript and CSS. Just pass in as many path globs as you like.

Oth­er set­tings of note:

• base — set to the root if the dev serv­er is run­ning, and oth­er­wise set it to /dist/ so our built assets are in their own direc­to­ry (and often not checked into Git).
• build.emptyOutDir — always delete every­thing from the outDir before building
• build.manifest — set to true so that the Rollup build will gen­er­ate a man­i­fest file of the pro­duc­tion assets
• build.outDir — spec­i­fies where the built pro­duc­tion assets should go, as a file sys­tem path rel­a­tive to the vite.config.js file.
• build.rollupOptions.input — set to an object that has key/​value pairs for each of our entry­point scripts (need­ed since we’re not using an index.html as our appli­ca­tion entry­point). The lead­ing ./ is impor­tant here, as absolute paths seem to break Com­mon­JS imports
• server.host — this is set to 0.0.0.0 so that it broad­casts to all IPv4 address­es on the local machine, need­ed as of Vite 2.3.0 or lat­er for Dock­er and VM-based setups 

Then to start up the Vite.js dev serv­er, you just do:

Your JavaScript files will be served up from http://localhost:3000 while the dev serv­er is running.

When it’s time to do a pro­duc­tion build, you just do:

And your pro­duc­tion assets will be built for your via Rollup, ready to deploy.

For more infor­ma­tion on Vite.js itself, check out the excel­lent Vite.js doc­u­men­ta­tion.

Link Using Vite.js with Craft CMS

Cre­ate your JavaScript, Type­Script, Vue sin­gle file com­po­nents, etc. as you nor­mal­ly would. Let’s say we store them in the direc­to­ry /src/js/

Here’s an exam­ple Type­Script file (remem­ber, it could be JavaScript too):

Any CSS that we want processed via PostC­SS needs to be import­ed via JavaScript. We don’t include the CSS in our tem­plates via <link rel="stylesheet"> tags, the plu­g­in does it for us.

Side note: as of Vite 2.3.0, the vite/­dy­nam­ic-import-poly­fill is no longer required to be imported.

That’s it. Then in our Twig tem­plates, we just need to ref­er­ence the file via a Twig func­tion pro­vid­ed by the Vite plugin:

The paths to your scripts are always rel­a­tive to the project root, which by default is the same direc­to­ry as the vite.config.js

In devel­op­ment with the Vite.js dev serv­er run­ning, this will gen­er­ate a tag that looks like this:

The CSS will be inject­ed auto­mat­i­cal­ly into the DOM via inline <style> tags while the dev serv­er is running.

In pro­duc­tion with­out the Lega­cy plu­g­in, the Twig func­tion will gen­er­ate the fol­low­ing tags:

Remem­ber that any <script type="module"> scripts are down­loaded with­out block­ing the HTML pars­er, and exe­cut­ed in order after the DOM is parsed, they are non-blocking.

Here’s an image from the Google JavaScript Mod­ules primer on how scripts load:

Since we’re using the Lega­cy plu­g­in for dual mod­ern + lega­cy builds, we’ll get even more tags gen­er­at­ed automatically:

This includes:

• Safari 10.1 nomod­ule fix script
• Lega­cy nomodule poly­fills for dynam­ic imports for old­er browsers
• Mod­ern app.js mod­ule for mod­ern browsers
• Extract­ed CSS, loaded asyn­chro­nous­ly by default
• Lega­cy app.js script for lega­cy browsers

This is the module/​nomodule pat­tern that’s been in use for years to allow for mod­ern and lega­cy JavaScript bundles.

Mod­ules that are dynam­i­cal­ly loaded via one of your entry scripts will appear in the brows­er as <link rel="modulepreload"> — check out the Pre­load­ing Mod­ules for infor­ma­tion on that.

Link Live Reload through Twig Errors

The Vite plu­g­in includes sup­port for live reload­ing through Twig error pages. You just need to set the errorEntry set­ting in the config/vite.php file, e.g.:

Then the page will auto-reload when­ev­er you fix the error!

Link Vite-processed assets

This is cribbed from the Lar­avel Vite inte­gra­tion docs:

There is cur­rent­ly an unsolved issue when ref­er­enc­ing assets in files processed by Vite, such as a Vue or CSS file. In devel­op­ment, URLs will not be prop­er­ly rewrit­ten.

Addi­tion­al­ly, there is cur­rent­ly no way to get the path of a Vite-processed asset (eg. an image that was import­ed in a Vue SFC) from the back-end, since the man­i­fest does not ref­er­ence the orig­i­nal file path. In most cas­es, this should not be an issue, as this is not a com­mon use case.

What you can do is lever­age the /public Pub­lic Direc­to­ry for sta­t­ic assets in Vite, so the URLs will not get rewritten.

The basic prob­lem is if you have a CSS rule like:

and your local dev runs off of some­thing like myhost.test then the image will be ref­er­enced as:

Which then resolves to:

When what you real­ly want is for it to be com­ing from the Vite dev server:

This is only a prob­lem when you’re using Vite with a back­end sys­tem like Craft CMS, where the host you run the web­site from is dif­fer­ent from where the Vite dev serv­er runs.

To work around this, as of Vite ^2.7.0 you can use the server.origin con­fig to tell Vite to serve the sta­t­ic assets it builds from the Vite dev serv­er, and not the web­site server:

This issue was dis­cussed in detail, and fixed via a pull request that was rolled into Vite ^2.6.0 in the form of the ori­gin setting.

Link A peek at the manifest.json

Since a good bit of what the Vite plu­g­in does to make the mag­ic hap­pen is pars­ing the manifest.json file that is built for pro­duc­tion builds, let’s have a look at it.

You don’t need to know any of this to use Vite, it’s just for curiosity’s sake

Here’s an exam­ple manifest.json that has some dynam­ic imports, and uses the Lega­cy plu­g­in for mod­ern + lega­cy builds:

This for­mat for the manifest.json is new as of Vite 2.x, and is quite a depar­ture of the typ­i­cal key/​value pair manifest.json gen­er­at­ed by your typ­i­cal web­pack build.

Each top-lev­el object rep­re­sents at least one JavaScript entry point, and lists any JavaScript that it imports, as well as any JavaScript that it dynam­i­cal­ly imports.

• file — is the built JavaScript file
• src — is the orig­i­nal source file used to build it

Then any CSS files that were extract­ed from the entry point is also listed.

The Vite 2.x man­i­fest is almost more of a depen­den­cy graph than any­thing else, which makes sense.

The Vite plu­g­in takes care of pars­ing all of the manifest.json to find the file you’re request­ing on the fron­tend, and ensure tags are gen­er­at­ed for it, and all of its depen­den­cies (JavaScript and CSS).

Link Try it yourself!

If you’d like to give Vite a spin with Craft CMS, we’ve made it super easy to do. There’s a Vite branch of the nystudio107/​craft boil­er­plate setup.

All you’ll need is Dock­er desk­top for your plat­form installed to get going! Just type the fol­low­ing in your terminal:

Ensure no oth­er local devel­op­ment tools are run­ning that might be using ports 8000, 3306, & 3000, then to get the project up and run­ning, type:

The ini­tial start­up will take some time, because it’s build­ing all of the Dock­er images, doing an npm install, doing a composer install, etc.

Wait until you see the fol­low­ing to indi­cate that the PHP con­tain­er is ready:

…and the fol­low­ing to indi­cate that the Vite con­tain­er is ready:

Then nav­i­gate to http://localhost:8000 to use the site; the Vite dev serv­er runs off of http://localhost:3000

If you view the brows­er Devel­op­er Con­sole, you should see the fol­low­ing to indi­cate that Vite is run­ning Hot Mod­ule Replace­ment (HMR):

Then feel free to see the Vite HMR in action by edit­ing any of the JavaScript, Vue com­po­nents, CSS, or Twig files in the src/ directory!

Link Bundling it all up

As Evan You, the cre­ator of Vite.js (and Vue.js) said:

It is NOT Vite’s goal to com­plete­ly replace web­pack. There are prob­a­bly a small num­ber of features/​capabilities that some exist­ing web­pack projects rely on that does­n’t exist in Vite, but those fea­tures are in the long tail and are only need­ed by a small num­ber of pow­er users who write bespoke web­pack con­fig­u­ra­tion.
…
How­ev­er, in the con­text of the gen­er­al web dev pop­u­la­tion, 90% of exist­ing devs and 100% of begin­ners don’t need or care about these long tail fea­tures.
…
So — try it, and if it does­n’t work for you, stick to webpack.

I think Vite.js is com­pelling enough that it’s def­i­nite­ly worth giv­ing it a whirl. The speed and sim­plic­i­ty real­ly are remarkable.

If you’re a Craft CMS plu­g­in devel­op­er, check out the nys­tu­dio107/craft-plu­g­in-vite pack­age as a way to inte­grate a Vite.js build­chain into your plugins.

If you want to learn more, check out the Vite Awe­some page for more, well, awe­some Vite.js plu­g­ins, inte­gra­tions, and tutorials.

Hap­py bundling!