[Docs] Add a migration guide from Webpack Encore

Author: Kocal

doc/index.rst

@@ -7,6 +7,11 @@ or even change drastically.
 Webpack Encore gave Symfony first-class asset integration for Webpack. Symfony Reprise brings the same to `Vite`_
 and `Rsbuild`_.
 
+.. tip::
+
+    Still using Webpack Encore? See `Migrating from Webpack Encore`_ below: it maps every ``Encore.*`` call to its
+    Vite/Rsbuild or Reprise equivalent.
+
 Vite and Rsbuild already handle **Sass/Less/PostCSS**, **TypeScript**, **JSX/Vue/Svelte**, **code splitting**,
 **content hashing**, **source maps**, **minification** and **HMR** on their own, so Symfony Reprise does not
 reimplement any of that. It covers only the Symfony-side glue the bundlers leave out:
@@ -608,6 +613,123 @@ If you set ``asset_package``, define that package with ``version: false``:
                 reprise:
                     version: false
 
+Migrating from Webpack Encore
+-----------------------------
+
+Reprise is Webpack Encore's successor for Vite and Rsbuild, so the move splits in two. The Symfony side (the bundle
+and your Twig templates) barely changes. Your ``webpack.config.js`` mostly goes away: Vite and Rsbuild do natively
+what most ``Encore.*`` calls set up, so you delete those calls rather than translate them. What is left maps to a
+Reprise plugin option or a bundler plugin.
+
+The Symfony side
+~~~~~~~~~~~~~~~~
+
+Reprise ships its own ``RepriseBundle`` and does not use `WebpackEncoreBundle`_, so swap the Composer package:
+
+.. code-block:: terminal
+
+    $ composer remove symfony/webpack-encore-bundle
+    $ composer require symfony/reprise
+
+In your templates the Twig functions keep the same shape, with the ``encore_`` prefix becoming ``reprise_`` (the full
+list is under `Rendering asset tags`_):
+
+.. code-block:: twig
+
+    {# before #}
+    {{ encore_entry_link_tags('app') }}
+    {{ encore_entry_script_tags('app') }}
+
+    {# after #}
+    {{ reprise_entry_link_tags('app') }}
+    {{ reprise_entry_script_tags('app') }}
+
+The bundle config carries over almost key-for-key: ``webpack_encore.output_path`` becomes ``reprise.output_path``,
+and ``crossorigin``, ``preload``, ``cache``, ``strict_mode``, ``script_attributes`` and ``link_attributes`` all exist
+under ``reprise`` with the same meaning. Encore's ``builds`` option maps to `Multiple builds`_.
+
+Your build config
+~~~~~~~~~~~~~~~~~
+
+Most of ``webpack.config.js`` has no equivalent, because the bundler already does the work. The Symfony glue Encore
+layered on top of Webpack stays, as a Reprise plugin option:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Webpack Encore
+     - Reprise
+   * - ``setOutputPath()`` / ``setPublicPath()``
+     - plugin ``outputPath`` / ``publicPath`` (the defaults fit a standard project)
+   * - ``addEntry()`` / ``addEntries()``
+     - the bundler's own entry input: Vite ``build.rollupOptions.input``, Rsbuild ``source.entry``
+   * - ``enableVersioning()``
+     - nothing to do, content hashing is on by default
+   * - ``enableIntegrityHashes()``
+     - plugin ``integrity: { enabled: true }`` (see `Subresource Integrity`_)
+   * - ``copyFiles()``
+     - plugin ``copy: [ ... ]`` (see `File copy`_)
+   * - ``enableStimulusBridge()``
+     - plugin ``stimulus: 'assets/controllers.json'`` (see `Symfony UX / Stimulus controllers`_)
+   * - ``configureDevServerOptions()``
+     - nothing to do: run ``vite`` or ``rsbuild dev`` and Reprise points Twig at it
+
+Everything Vite and Rsbuild handle themselves, you drop:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Webpack Encore
+     - Now handled by the bundler
+   * - ``enableSassLoader()`` / ``enableLessLoader()`` / ``enableStylusLoader()``
+     - install the preprocessor and import the file (Vite out of the box, Rsbuild via ``@rsbuild/plugin-sass`` and friends)
+   * - ``enablePostCssLoader()``
+     - add a ``postcss.config.js``, picked up automatically
+   * - ``enableTypeScriptLoader()`` / ``configureBabel()`` / ``configureBabelPresetEnv()``
+     - native transpilation (Vite via esbuild, Rsbuild via SWC); set targets with ``browserslist`` or ``build.target``
+   * - ``splitEntryChunks()`` / ``configureSplitChunks()``
+     - native code splitting
+   * - ``enableSourceMaps()``
+     - native (Vite ``build.sourcemap``)
+   * - ``configureImageRule()`` / ``configureFontRule()`` / ``configureFilenames()``
+     - native asset handling and output naming
+   * - ``addAliases()``
+     - ``resolve.alias``
+   * - ``addExternals()``
+     - Vite ``build.rollupOptions.external``, Rsbuild ``output.externals``
+   * - ``cleanupOutputBeforeBuild()``
+     - native (Vite ``build.emptyOutDir``, Rsbuild cleans by default)
+
+Framework presets become the bundler's own plugin:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Webpack Encore
+     - Vite
+     - Rsbuild
+   * - ``enableReactPreset()``
+     - ``@vitejs/plugin-react``
+     - ``@rsbuild/plugin-react``
+   * - ``enableVueLoader()``
+     - ``@vitejs/plugin-vue``
+     - ``@rsbuild/plugin-vue``
+   * - ``enablePreactPreset()``
+     - ``@preact/preset-vite``
+     - ``@rsbuild/plugin-preact``
+   * - ``enableSvelte()``
+     - ``@sveltejs/vite-plugin-svelte``
+     - ``@rsbuild/plugin-svelte``
+
+A few Encore features have no direct replacement:
+
+- ``autoProvideVariables()`` / ``autoProvidejQuery()``: prefer importing what you use. To inject a global anyway, use
+  ``@rollup/plugin-inject`` under Vite or ``rspack.ProvidePlugin`` (through Rsbuild's ``tools.rspack``).
+- ``enableBuildNotifications()`` and the ESLint integration are gone: run your linter as its own script, outside the
+  build.
+- ``Encore.isProduction()`` / ``isDev()`` / ``when()``: branch on the bundler mode instead, e.g.
+  ``defineConfig(({ command }) => ...)`` where ``command`` is ``'build'`` or the dev command.
+
 .. _Vite: https://vite.dev/
 .. _Rsbuild: https://rsbuild.dev/
 .. _`@symfony/stimulus-bridge`: https://github.com/symfony/stimulus-bridge