symfony · Kocal · Jun 3, 2025 · Jun 3, 2025
diff --git a/src/Swup/CHANGELOG.md b/src/Swup/CHANGELOG.md
@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.27.0
+
+-   Deprecate the package
+
 ## 2.13.2
 
 -   Revert "Change JavaScript package to `type: module`"

diff --git a/src/Swup/README.md b/src/Swup/README.md
@@ -1,5 +1,113 @@
 # Symfony UX Swup
 
+> [!WARNING]
+> **Deprecated**: This package has been **deprecated** in 2.x and will be removed in the next major version.
+
+We
+To keep the same functionality in your Symfony application, follow these migration steps:
+
+1. Install the `swup` library and its plugins:
+
+```bash
+# If using Symfony AssetMapper:
+php bin/console importmap:require swup @swup/fade-theme @swup/slide-theme @swup/forms-plugin @swup/debug-plugin
+
+# If using NPM (e.g.: with Webpack Encore):
+npm install swup @swup/fade-theme @swup/slide-theme @swup/forms-plugin @swup/debug-plugin
+```
+
+2. Add the following code to your app:
+
+<details><summary><code>assets/controllers/swup_controller.js</code></summary>
+
+```javascript
+import { Controller } from '@hotwired/stimulus';
+import Swup from 'swup';
+import SwupFadeTheme from '@swup/fade-theme';
+import SwupSlideTheme from '@swup/slide-theme';
+import SwupFormsPlugin from '@swup/forms-plugin';
+import SwupDebugPlugin from '@swup/debug-plugin';
+
+export default class extends Controller {
+    static values = {
+        containers: Array,
+        mainElement: String,
+        animateHistoryBrowsing: Boolean,
+        animationSelector: String,
+        cache: Boolean,
+        linkSelector: String,
+        theme: String,
+        debug: Boolean,
+    };
+
+    connect() {
+        const dataContainers = this.containersValue;
+        const mainElement = this.mainElementValue || dataContainers[0] || '#swup';
+        const allElements = [mainElement].concat(dataContainers);
+        const containersList = allElements.filter((item, index) => {
+            return allElements.indexOf(item) === index;
+        });
+
+        const options = {
+            containers: containersList,
+            plugins: [
+                'slide' === this.themeValue
+                    ? new SwupSlideTheme({ mainElement: mainElement })
+                    : new SwupFadeTheme({ mainElement: mainElement }),
+                new SwupFormsPlugin(),
+            ],
+        };
+
+        if (this.hasMainElementValue) {
+            options.mainElement = this.mainElementValue;
+        }
+
+        if (this.hasAnimateHistoryBrowsingValue) {
+            options.animateHistoryBrowsing = this.animateHistoryBrowsingValue;
+        }
+        if (this.hasAnimationSelectorValue) {
+            options.animationSelector = this.animationSelectorValue;
+        }
+        if (this.hasCacheValue) {
+            options.cache = this.cacheValue;
+        }
+        if (this.hasLinkSelectorValue) {
+            options.linkSelector = this.linkSelectorValue;
+        }
+        if (this.debugValue) {
+            options.plugins.push(new SwupDebugPlugin());
+        }
+
+        this.dispatchEvent('pre-connect', { options });
+        const swup = new Swup(options);
+        this.dispatchEvent('connect', { swup, options });
+    }
+
+    dispatchEvent(name, payload) {
+        this.dispatch(name, { detail: payload, prefix: 'swup' });
+    }
+}
+```
+
+</details>
+
+3. Replace the `symfony--ux-swup` occurrences in your templates with `swup`, for example:
+
+```diff
+-<body {{ stimulus_controller('symfony/ux-swup/swup') }}>
++<body {{ stimulus_controller('swup') }}>
+```
+
+4. Remove `symfony/ux-swup` from your dependencies:
+
+```bash
+composer remove symfony/ux-swup
+```
+
+You're done!
+
+---
+
 Symfony UX Swup is a Symfony bundle integrating [Swup](https://swup.js.org/) in
 Symfony applications. It is part of [the Symfony UX initiative](https://ux.symfony.com/).
 

diff --git a/src/Swup/doc/index.rst b/src/Swup/doc/index.rst
@@ -1,6 +1,13 @@
 Symfony UX Swup
 ===============
 
+.. warning::
+
+    **Deprecated: This package has been deprecated in 2.x and will be removed in the next major version.**
+
+    To keep the same functionality in your Symfony application, please follow the migration steps
+    from the `Symfony UX Swup README.md`_.
+
 Symfony UX Swup is a Symfony bundle integrating `Swup`_ in
 Symfony applications. It is part of `the Symfony UX initiative`_.
 
@@ -207,3 +214,4 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Swup Options`: https://swup.js.org/options
 .. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`@symfony/ux-swup npm package`: https://www.npmjs.com/package/@symfony/ux-swup
+.. _`Symfony UX Swup README.md`: https://github.com/symfony/ux/tree/2.x/src/Swup/README.md
diff --git a/src/Swup/src/DependencyInjection/SwupExtension.php b/src/Swup/src/DependencyInjection/SwupExtension.php
@@ -16,6 +16,8 @@
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 
+trigger_deprecation('symfony/ux-swup', '2.27.0', 'The package is deprecated and will be removed in 3.0. Follow the migration steps in https://github.com/symfony/ux/tree/2.x/src/Swup to keep using Swup in your Symfony application.');
+
 /**
  * @internal
  */

diff --git a/src/Swup/src/SwupBundle.php b/src/Swup/src/SwupBundle.php
@@ -13,6 +13,8 @@
 
 use Symfony\Component\HttpKernel\Bundle\Bundle;
 
+trigger_deprecation('symfony/ux-swup', '2.27.0', 'The package is deprecated and will be removed in 3.0. Follow the migration steps in https://github.com/symfony/ux/tree/2.x/src/Swup to keep using Swup in your Symfony application.');
+
 /**
  * @final
  */

diff --git a/ux.symfony.com/tests/baseline-ignore b/ux.symfony.com/tests/baseline-ignore
@@ -1,2 +1,3 @@
 %Since symfony/ux-typed 2\.27\.0: The package is deprecated and will be removed in 3\.0\.%
 %Since symfony/ux-lazy-image 2\.27\.0: The package is deprecated and will be removed in 3\.0\.%
+%Since symfony/ux-swup 2\.27\.0: The package is deprecated and will be removed in 3\.0\.%
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,6 +13,8 @@ @@
     use Symfony\Component\HttpKernel\Bundle\Bundle;
+    trigger_deprecation('symfony/ux-swup', '2.27.0', 'The package is deprecated and will be removed in 3.0. Follow the migration steps in https://github.com/symfony/ux/tree/2.x/src/Swup to keep using Swup in your Symfony application.');
     /**
      * @final
      */
@@ Expand Down @@