docs: explain the reason for this script

README.md

@@ -69,6 +69,34 @@ The script does the following:
 This script is intended to add an authentication layer to static sites hosted on Vercel.
 It's highly opinionated and might not work for all use cases.
 
+## Why is this script necessary?
+
+We faced challenges deploying static assets with API routes created during build time, such as with the [Technology Radar](https://github.com/porscheofficial/porschedigital-technology-radar), to Vercel.
+This script explicitly defines which assets to deploy on which infrastructure.
+
+#### First try
+During the build process, we created a directory `/build` and moved the functions to `/build/api`.
+Unfortunately, Vercel treated all files in that build directory as static files and didn't execute the functions.
+
+#### Second try
+We created a `vercel.json` and referenced the API Directory. This resulted in an error, because the API Directory is not part of the repository but is only created during build time.
+The `vercel.json` File seems to be interpreted before the build.
+
+#### Third try
+We created the API directory in the root of the repository (`/api`) and let Vercel transpile the typescript files.
+Unfortunately, this resulted in an error because `next-auth` uses `__dirname` which is not available in the Edge Environment (Middleware).
+Running esbuild manually allows to replace the `__dirname` variable.
+
+#### Fourth try – Working Alternative
+Following the first approach, we created the API directory within the build directory (`/build/api`), but with the difference that we did that via Github Actions and only then pushed the artifacts to Vercel.
+That means, after the build, we cd into the build directory (`/build`) and then run the CLI `vercel deploy`.
+That works because then all the assets are already there, and Vercel correctly interprets the API files as functions.
+The downside of this approach is that we do not leverage Vercel Build Infrastructure.
+
+#### Solution
+We decided implement the Vercel Output API to tell Vercel exactly how to run our artifacts.
+By doing that, it is possible to create the assets during build time on Vercel's Infrastructure and then deploy them correctly.
+
 ## License
 
 See [LICENSE.md](LICENSE.md) for more information.

src/cli.ts

@@ -23,24 +23,6 @@ const CWD = process.cwd();
 const EXTENSIONS_ROOT_DIR = path.join(__dirname, "extensions");
 const TMP_DIR = path.join(CWD, ".vercel-static-extensions");
 
-// We encountered some bugs when trying to deploy our assets to Vercel
-// ## First try
-// During build process we created a directory "build" and added the functions via the "api/" directory
-// Unfortunately, Vercel treated all files in that build directory as static files and didn't execute the functions
-// ## Second try
-// We created a vercel.json and pointing to the API Directory. This resulted in an error, because the API Directory is not part of the repository but is only created during build time.
-// The vercel.json seems to be interpreted before the build.
-// ## Third try
-// We create the API directory in the root of the repository and let Vercel transpile the typescript files.
-// Unfortunately, this resulted in an error because next-auth uses __dirname which is not available in the Edge Environment (Middleware).
-// Running esbuild before allows to replace the __dirname variable with an empty string.
-// ## Fourth try – Working Alternative
-// Follow the first approach and create the API directory within the build directory, but don't do that on Vercel but in Github Actions
-// cd into the build directory, and then run "vercel deploy". That works, because then all the assets are already there and Vercel correctly interprets the API files as functions
-// The downside of this approach is, that it costs GitHub Action Minutes.
-// ## Solution
-// We decided implement the Vercel Output API to tell Vercel exactly how to run our artifacts.
-
 // First load the configuration file if there's one
 // The naming convention is vercel-static-extensions.config.json