Installation

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

Then install the bundle using Composer and Symfony Flex:

1
2
3
4
5
6
7
8

$ composer require symfony/ux-svelte

$ npm install --force
$ npm run watch

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

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

Next, install a package to help Svelte:

1
2
3
4

$ npm install svelte-loader --save-dev

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

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

Usage

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

1
2
3
4

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

registerSvelteControllerComponents(require.context('./svelte/controllers', true, /\.svelte$/));

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

You can render any Svelte controller component in Twig using the svelte_component().

For example:

1
2
3
4
5
6

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

<div>Hello {name}</div>

1
2

{# templates/home.html.twig #}
<div {{ svelte_component('Hello', { '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|global>Hello {name}</div>

1
2

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

Using with AssetMapper

Because the .svelte file format isn't pure JavaScript, using this library with AssetMapper requires some extra steps.

1. Compile your .svelte files to pure JavaScript files. This can be done by using the svelte/compiler library, but is a bit of a non-standard process. For an example, see https://github.com/symfony/ux/blob/2.x/ux.symfony.com/bin/compile_svelte.js.
2. Point this library at the "built" controllers directory that contains the final JavaScript files:

1
2
3

# config/packages/svelte.yaml
svelte:
    controllers_path: '%kernel.project_dir%/assets/build/svelte/controllers'

Also, inside of your .svelte files, when importing another component, use the .js extension:

1
2

// use PackageList.js even though the file is named PackageList.svelte
import PackageList from '../components/PackageList.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