From e5793d1b4cb117c96fe51fb2d3c3f6b55f6f505b Mon Sep 17 00:00:00 2001
From: Jeppe Reinhold <jeppe@reinhold.is>
Date: Thu, 5 Sep 2024 13:43:04 +0200
Subject: [PATCH] add readme section about legacy api support

---
 ERRORS.md |  2 ++
 README.md | 25 +++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/ERRORS.md b/ERRORS.md
index bce51fd..5d616ec 100644
--- a/ERRORS.md
+++ b/ERRORS.md
@@ -352,6 +352,8 @@ It cannot be a shorthand or a dynamic value.
 You are using legacy template API, with deprecated components.\
 To enable support for legacy API, tweak this addon options in your _(`./.storybook/main.(j|t)s`)_ file:
 
+See [the Legacy API section](./README.md#legacy-api) for more details.
+
 ```diff
 addons: [
     // ... other addons
diff --git a/README.md b/README.md
index ee269b0..73cf988 100644
--- a/README.md
+++ b/README.md
@@ -257,6 +257,31 @@ If you need to customize the type of the `args`, you can pass in a generic type
 const { Story } = defineMeta<{ anotherProp: boolean }>( ... );
 ```
 
+### Legacy API
+
+Version 5 of the addon changes the API from v4 in key areas, as described above. However a feature flag has been introduced to maintain support for the `<Template>`-based legacy API as it was prior to v5.
+
+To enable supoprt for the legacy API, make the following change to your main Storybook config:
+
+```diff
+export default {
+  addons: [
+-    '@storybook/addon-svelte-csf',
++    {
++      name: '@storybook/addon-svelte-csf',
++      options: {
++         legacyTemplate: true
++    },
+    ...
+  ],
+  ...
+}
+```
+
+This can make the overall experience slower, because it adds more transformation steps on top of the existing ones. It should only be used temporarily while migrating to the new API. It's highly likely that the legacy support will be dropped in future major versions of the addon.
+
+The legacy support is not bullet-proof, and it might not work in all scenarios that previously worked. If you're experiencing issues or getting errors after upgrading to v5, try migrating the problematic stories files to the modern API.
+
 ## Version compatibility
 
 ### latest