Symfony UX Vue.js

Installation

Install the bundle using Composer and Symfony Flex:

1

$ composer require symfony/ux-vue

The Flex recipe will automatically set things up for you, like adding .enableVueLoader() to your webpack.config.js file and adding code to load your Vue components inside assets/app.js.

Next, install a package to help Vue:

1
2

$ npm install -D vue-loader --force
$ npm run watch

That's it! Any files inside assets/vue/controllers/ can now be rendered as Vue components.

Usage

The Flex recipe will have already added the registerVueControllerComponents() code to your assets/app.js file:

1
2
3
4

// assets/app.js
import { registerVueControllerComponents } from '@symfony/ux-vue';

registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/));

This will load all Vue components located in the assets/vue/controllers directory. These are known as Vue controller components: top-level components that are meant to be rendered from Twig.

You can render any Vue controller component in Twig using the vue_component().

1
2
3
4
5
6
7
8
9
10

// assets/vue/controllers/Hello.vue
<template>
    <div>Hello {{ name }}!</div>
</template>

<script setup>
    defineProps({
        name: String
    });
</script>

1
2

{# templates/home.html.twig #}
<div {{ vue_component('Hello', { 'name': app.user.fullName }) }}></div>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// assets/app.js
document.addEventListener('vue:before-mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that will be injected to the component
        app, // The Vue application instance
    } = event.detail;

    // Example with Vue Router
    const router = VueRouter.createRouter({
        history: VueRouter.createWebHashHistory(),
        routes: [
            /* ... */
        ],
    });

    app.use(router);
});

1
2
3
4
5
6
7

document.addEventListener('vue:mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that are injected to the component
    } = event.detail;
});

1
2
3
4
5
6

document.addEventListener('vue:unmount', (event) => {
    const {
        componentName, // The Vue component's name
        props, // The props that were injected to the component
    } = event.detail;
});

1
2
3
4
5

#Route('/survey/{path<.+>}')
public function survey($path = ''): Response
{
    // render the template
}

1
2
3
4
5
6
7
8
9
10

const router = VueRouter.createRouter({
    history: VueRouter.createWebHistory(),
    routes: [
        { path: '/survey/list', component: ListSurveys },
        { path: '/survey/create', component: CreateSurvey },
        { path: '/survey/edit/:surveyId', component: EditSurvey },
    ],
});

app.use(router);

Using with AssetMapper

The Vue single-file component (i.e. .vue) file format is not pure JavaScript and cannot currently be converted to pure JavaScript outside of a bundler like Webpack Encore or Vite. This means that the .vue file format cannot be used with AssetMapper.

If you do still want to use Vue with AssetMapper, you can do so by avoiding the .vue file format. For example, https://github.com/symfony/ux/blob/2.x/ux.symfony.com/assets/vue/controllers/PackageSearch.js.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html