Installation

Before you start, make sure you have Symfony UX configured in your app.

Then install the bundle using Composer and Symfony Flex:

1
2
3
4
5
6
7
8
9

$ composer require symfony/ux-svelte

# Don't forget to install the JavaScript dependencies as well and compile
$ npm install --force
$ npm run watch

# or use yarn
$ yarn install --force
$ yarn watch

You also need to add the following lines at the end to your assets/app.js file:

1
2
3
4
5
6
7
8
9
10
11
12
13

// assets/app.js
import { registerSvelteControllerComponents } from '@symfony/ux-svelte';

// Registers Svelte controller components to allow loading them from Twig
//
// Svelte controller components are components that are meant to be rendered
// from Twig. These component can then rely on other components that won't be
// called directly from Twig.
//
// By putting only controller components in `svelte/controllers`, you ensure that
// internal components won't be automatically included in your JS built file if
// they are not necessary.
registerSvelteControllerComponents(require.context('./svelte/controllers', true, /\.svelte$/));

To make sure Svelte components can be loaded by Webpack Encore, you need to add and configure the svelte-loader library in your project :

1
2
3
4

$ npm install svelte svelte-loader --save-dev

# or use yarn
$ yarn add svelte svelte-loader --dev

Enable it in your webpack.config.js file :

1
2
3
4
5

// webpack.config.js
Encore
    // ...
    .enableSvelte()
;

Usage

UX Svelte works by using a system of Svelte controller components: Svelte components that are registered using registerSvelteControllerComponents() and that are meant to be rendered from Twig.

When using the registerSvelteControllerComponents() configuration shown previously, all Svelte components located in the directory assets/svelte/controllers are registered as Svelte controller components.

You can then render any Svelte controller component in Twig using the svelte_component() function:

1
2
3
4
5
6

// assets/svelte/controllers/MyComponent.svelte
<script>
    export let name = "Svelte";
</script>

<div>Hello {name}</div>

1
2

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

If your Svelte component has a transition that you want to play on initial render, you can use the third argument intro of the svelte_component() function like you would do with the Svelte client-side component API:

1
2
3
4
5
6
7

// assets/svelte/controllers/MyAnimatedComponent.svelte
<script>
    import { fade } from 'svelte/transition';
    export let name = "Svelte";
</script>

<div transition:fade>Hello {name}</div>

1
2

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

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