Download the PHP package opctim/vite-bundle-php72 without Composer

ViteBundle : Symfony integration with Vite

This bundle helping you render all of the dynamic script and link tags needed. Essentially, he provides two twig functions to load the correct scripts into your templates.

Installation

Before you start, make sure you don't have a package.json file otherwise, or if you come from Webpack Encore, check the migration documentation.

Install the bundle with :

Add this twig functions in any template or base layout where you need to include a JavaScript entry.

if you experience unwanted reloads of your application, read the section https/http in development.

if you want to reduce the FOUC (flash of unstyled content), read the section css file as entrypoint.

if you are using React, you have to add this option in order to have FastRefresh.

If you want to install the bundle without the community recipe, check the manual installation.

Bundle Configuration

If you change some properties in your vite.config.js file, you probably need to create a config/packages/pentatrion_vite.yaml file to postpone these changes. it concerns server.host, server.port, server.https and build.outdir (and also base).

default configuration

Vite config

For the transparency, I decided not to create an overlay of the config file vite.config.js. You can check the full documentation of the vite-plugin-symfony in the github repository.

Twig functions

The bundle provide 2 twig functions both of which accept an optional second parameter of options and an optional third parameter buildName if you have multiple builds (look at #multiple vite configurations section).

vite_entry_script_tags

options:

• dependency: 'react' | null
• attr: Array (an array of extra attributes)

vite_entry_link_tags

options:

• attr: Array (an array of extra attributes)

if you have defined multiple builds

Vite Assets managements

When you reference assets files in your js or css files, you should remember that you need to use a relative path if you wants Vite process your file.

• all your files defined with an absolute path will be ignored by Vite and will be left as is in your build files. You can specify an absolute path relative to your public folder. this practice is not recommended because your asset files will not be versioned.
• all your files defined with a relative path will be processed by Vite. The paths are relative to the file where they are referenced. Any assets referenced via a relative path will be re-written, versioned, and bundled by Vite.

Symfony Asset Component

Whenever you build your Vite app, two configuration files are generated in your output folder (default location: public/build/): manifest.json (generated by vite core), entrypoints.json (generated by vite-plugin-symfony).

The manifest.json file is needed to get the versioned filename of assets files, like font files or image files.

so you can use Symfony's asset component and its asset function to take advantage of this file. To be able to use this during development you will have to use ViteAssetVersionStrategy.

You can also use the asset twig function by specifing your asset file path relative to your root path (for compatibility reason with vite generated manifest file) specified in your vite.config.js

You can use this asset() function only with assets referenced by JavaScript or CSS files. If you want to make Vite aware of others assets you can import directory of assets into your application's entry point. For example il you want to version all images stored in assets/images you could add the following in your app entrypoint.

Multiple Vite Configurations

It's possible to combine multiple vite configuration files. Here is a possible configuration model.

package.json

define 2 vite config files vite.build1.config.js and vite.build2.config.js.

in your config/packages/pentatrion_vite.yaml file

in your templates

to show your assets in dev mode

Optional : if you want to use asset symfony component with custom strategy you need to add extra config...

after you can use your assets like this:

Usage tips

CSS files as entrypoint

This section talk about FOUC (Flash of unstyled content) for development only. Normally this phenomenon should not occur after a build process.

By default if you import your css files from js entry point, the vite dev server create only one entrypoint (<script src="http://localhost:5173/build/assets/app.js" type="module"></script>) for your js and css files. Your css content will be loaded after. This result to a period of time when the content of the page will not be styled. It can be boring.

You can however provide a css/scss/... file as entrypoint and it will be directly inserted as a link tag <link rel="stylesheet" href="http://localhost:5173/build/assets/theme.scss">. In this way your browser will wait for the loading of your theme.scss file before rendering the page.

note : still add the 2 twig functions vite_entry_link_tags / vite_entry_script_tags even if the entry point is a css file because ViteJs may need to insert his js code to enable the hmr

will render

during development.

Dependency Pre-Bundling

Initially in a Vite project, index.html is the entry point to your application. When you run your dev serve, Vite will crawl your source code and automatically discover dependency imports.

Because we don't have any index.html, Vite can't do this Pre-bundling step when he starts but when you browse a page where he finds a package he does not already have cached. Vite will re-run the dep bundling process and reload the page.

this behavior can be annoying if you have a lot of dependencies because it creates a lot of page reloads before getting to the final render.

you can limit this by declaring in the vite.config.js the most common dependencies of your project.

One file by entry point

Vite try to split your js files into multiple smaller files shared between entry points. In some cases, it's not a good choise and you can prefer output one js file by entry point.

https / http in Development

By default, your Vite dev server don't use https and can cause unwanted reload if you serve your application with https (probably due to invalid certificates ). Configuration is easier if you develop your application without https.

browse : http://127.0.0.1:8000

if you still want to use https you will need to generate certificates for your Vite dev server.

you can use mkcert : https://github.com/FiloSottile/mkcert

browse : https://127.0.0.1:8000

Dependency injection

if you want more control (like creating custom Twig functions), you can use dependency injection with EntrypointRenderer / EntrypointsLookup.

How this bundle works

would render in dev:

would render in prod:

In development environment, the bundle also acts as a proxy by forwarding requests that are not intended for it to the Vite dev server.

Migration

This version 3 is compatible with Vite v4. For migration from v2.X to v3, you just need to update your vite-plugin-symfony package to version >= 0.7.2.

Vite-bundle version 2 is compatible with Vite v3.

If you use previous version of the plugin consult migration page.