Symfony UX Svelte
Symfony UX Svelte is a Symfony bundle integrating Svelte in Symfony applications. It is part of the Symfony UX initiative.
Svelte is a JavaScript framework for building user interfaces. Symfony UX Svelte provides tools to render Svelte components from Twig, handling rendering and data transfers.
Symfony UX Svelte supports Svelte 3 and Svelte 4.
Installation
Note
This package works best with WebpackEncore. To use it with AssetMapper, see Using with AssetMapper.
Install the bundle using Composer and Symfony Flex:
1 2 3 4
$ composer require symfony/ux-svelte
$ npm install --force
$ npm run 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
$ npm install svelte-loader --save-dev
That's it! Any files inside assets/svelte/controllers/
can now be rendered as
Svelte components.
If you are using Svelte 4, you will have to add browser
, import
and svelte
to the conditionNames
array. This is necessary as per the Svelte 4 migration guide
for bundlers such as webpack, to ensure that lifecycle callbacks are internally invoked.
To modify the conditionNames
array, append the following changes to the bottom
of your webpack.config.js
file:
1 2 3 4 5
// webpack.config.js
- module.exports = Encore.getWebpackConfig();
+ const config = Encore.getWebpackConfig();
+ config.resolve.conditionNames = ['browser', 'import', 'svelte'];
+ module.exports = config;
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.
- Compile your
.svelte
files to pure JavaScript files. This can be done by using thesvelte/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. - 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