From 35dec6f8281e18cf1972a1f3004f0fece9de767d Mon Sep 17 00:00:00 2001
From: Daniel Maslowski <info@orangecms.org>
Date: Fri, 5 May 2023 14:38:58 +0200
Subject: [PATCH] MIGRATION: further clarify serving Storybook builds

This adds notes from https://github.com/storybookjs/storybook/issues/20157.
---
 MIGRATION.md | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/MIGRATION.md b/MIGRATION.md
index 376d4329d6be..c953269ec8a1 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -22,7 +22,9 @@
     - [Importing plain markdown files with `transcludeMarkdown` has changed](#importing-plain-markdown-files-with-transcludemarkdown-has-changed)
     - [Stories field in .storybook/main.js is mandatory](#stories-field-in-storybookmainjs-is-mandatory)
     - [Stricter global types](#stricter-global-types)
-    - [Dropped support for file URLs](#dropped-support-for-file-urls)
+    - [Deploying build artifacts](#deploying-build-artifacts)
+      - [Dropped support for file URLs](#dropped-support-for-file-urls)
+      - [Serving with nginx](#serving-with-nginx)
   - [7.0 Core changes](#70-core-changes)
     - [7.0 feature flags removed](#70-feature-flags-removed)
     - [Story context is prepared before for supporting fine grained updates](#story-context-is-prepared-before-for-supporting-fine-grained-updates)
@@ -800,11 +802,36 @@ Please follow up the [Configure your Storybook project](https://storybook.js.org
 
 In 6.x, you could declare and use [`globals`](https://storybook.js.org/docs/react/essentials/toolbars-and-globals) without declaring their corresponding `globalTypes`. We've made this more strict in 7.0, so that the `globalTypes` declaration is required, and undeclared globals will be ignored.
 
-#### Dropped support for file URLs
+#### Deploying build artifacts
 
-In 6.x it was possible to open a storybook from the file system. In 7.x, you must serve your static storybook with an HTTP server, e.g. `npx http-server storybook-static`.
+Starting with 7.x, we are using modern [ECMAScript Modules (ESM)](https://nodejs.org/api/esm.html).
 
-The reason for this change is that we're now using `.mjs` (modern ESM) and these are incompatible with the browser's CORS settings for file URLs.
+Those end up as `.mjs` files in your static Storybook artifact and need to be served as `application/javascript`, indicated by the `Content-Type` HTTP header.
+
+For a simple HTTP server to view a Storybook build, you can run `npx http-server storybook-static`.
+
+Note that [using the serve package](https://storybook.js.org/docs/react/faq#i-see-a-no-preview-error-with-a-storybook-production-build) will not work.
+
+##### Dropped support for file URLs
+
+In 6.x it was possible to open a Storybook build from the file system.
+
+ESM requires loading over HTTP(S), which is incompatible with the browser's CORS settings for `file://` URLs.
+
+So you now need to use a web server as described above.
+
+##### Serving with nginx
+
+With [nginx](https://www.nginx.com/), you need to extend [the MIME type handling](https://github.com/nginx/nginx/blob/master/conf/mime.types) in your configuration:
+
+```
+    include mime.types;
+    types {
+        application/javascript mjs;
+    }
+```
+
+It would otherwise default to serving the `.mjs` files as `application/octet-stream`.
 
 ### 7.0 Core changes