refactor(ui): rename VITE_APP_EXTENSIONS to VITE_EXAMPLE_EXTENSION

The name promised a list of extensions to install and delivered a boolean switch
for the bundled example — the only value it ever matched was the literal
"example", and no other value could do anything, because an extension has to be
imported to exist in the bundle at all.

`VITE_EXAMPLE_EXTENSION=true` says what it does. Which extensions are installed
stays the array in `activeExtensions.ts`, and there is no environment variable
for it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Nicholas Bucher <behappy54321@gmail.com>

Author: Charlesthebird

ui/docs/app-extensions.md

@@ -18,7 +18,7 @@ entry; nothing else in the application changes.
 
 Nothing is installed by default, including the bundled example. To see the example
 running without editing the file, start the dev server with
-`VITE_APP_EXTENSIONS=example yarn dev`.
+`VITE_EXAMPLE_EXTENSION=true yarn dev`.
 
 ---
 
@@ -81,7 +81,7 @@ installed, so a default build renders only what this project itself provides.
 Switch it on with:
 
 ```bash
-VITE_APP_EXTENSIONS=example yarn dev
+VITE_EXAMPLE_EXTENSION=true yarn dev
 ```
 
 Read that directory alongside this document — it exercises every extension point
@@ -524,10 +524,10 @@ two consequences of it are worth knowing:
 
 ### The two build-time exceptions
 
-`VITE_API_MODE` and `VITE_APP_EXTENSIONS` are the only variables in this UI that
+`VITE_API_MODE` and `VITE_EXAMPLE_EXTENSION` are the only variables in this UI that
 carry a `VITE_` prefix, and neither is a deployment setting:
 
-| | `VITE_API_MODE`, `VITE_APP_EXTENSIONS` | `EXTENSION_*` |
+| | `VITE_API_MODE`, `VITE_EXAMPLE_EXTENSION` | `EXTENSION_*` |
 |---|---|---|
 | Read with | `import.meta.env` | `readEnv` |
 | Fixed when | the bundle is built | the container starts |
@@ -540,9 +540,11 @@ read at runtime, so an extension setting never takes it — prefixed, the variab
 would no longer match the `EXTENSION_` prefix the init script and the dev server
 select on, and `readEnv` would quietly return the fallback.
 
-`VITE_APP_EXTENSIONS` is also not a way to install an extension. It only appends the
-bundled example, for the e2e suite and for a look at it running. Installing is the
-array.
+`VITE_EXAMPLE_EXTENSION=true` is a switch for the bundled example and nothing else.
+It cannot name an extension — an extension has to be *imported* to exist in the
+bundle at all, which is the same reason installing one is an edit to
+`activeExtensions.ts` rather than a setting. There is no environment variable that
+lists the installed extensions; the array is that list.
 
 ---
 

ui/playwright.config.ts

@@ -42,13 +42,13 @@ const MOCK_BACKEND = { VITE_API_MODE: "mock" };
  * stated in one place — and so a branch that installs an extension changes a
  * value instead of restructuring the `projects`/`webServer` blocks.
  *
- * `VITE_APP_EXTENSIONS` is pinned on the bare server for the same reason
+ * `VITE_EXAMPLE_EXTENSION` is pinned on the bare server for the same reason
  * `VITE_API_MODE` is: an inherited value must not be able to decide what a run
  * measures. Left unpinned, the bare project measures whatever the shell happened
  * to export.
  */
-const BARE_APP = { ...MOCK_BACKEND, VITE_APP_EXTENSIONS: "none" };
-const EXAMPLE_APP = { ...MOCK_BACKEND, VITE_APP_EXTENSIONS: "example" };
+const BARE_APP = { ...MOCK_BACKEND, VITE_EXAMPLE_EXTENSION: "false" };
+const EXAMPLE_APP = { ...MOCK_BACKEND, VITE_EXAMPLE_EXTENSION: "true" };
 
 /**
  * The third mode: one app, wired to a real backend.

ui/playwright/README.md

@@ -79,7 +79,7 @@ Which extensions a build installs is decided at build time, so "installed" and
 | Project | Server | Specs |
 |---|---|---|
 | `chromium` | bare — no extension, on `UI_LOOP_PORT` | everything not matching `*.withExtension.spec.ts` |
-| `chromium-with-extension` | `VITE_APP_EXTENSIONS=example`, on `UI_LOOP_PORT + 50` | `*.withExtension.spec.ts` |
+| `chromium-with-extension` | `VITE_EXAMPLE_EXTENSION=true`, on `UI_LOOP_PORT + 50` | `*.withExtension.spec.ts` |
 
 A spec opts into the extension-installed app by being named `*.withExtension.spec.ts`.
 

ui/playwright/globalSetup.ts

@@ -53,7 +53,7 @@ export default async function globalSetup(config: FullConfig): Promise<void> {
             `${baseUrl} was expected to serve the app with the example extension ` +
               `installed (project "${project.name}"), but no extension points are ` +
               `mounted. The server on that port came up without ` +
-              `VITE_APP_EXTENSIONS=example.`,
+              `VITE_EXAMPLE_EXTENSION=true.`,
           );
         }
         if (!wantsExtension && slots > 0) {

ui/src/appExtensions/activeExtensions.ts

@@ -14,12 +14,14 @@ import { exampleAppExtension } from "./example/exampleExtension";
  * the later entry wins. So list the extension whose opinion should prevail last.
  *
  * The worked example is not installed by default: it is documentation you can run,
- * not a feature of the application. `VITE_APP_EXTENSIONS=example` appends it, which
+ * not a feature of the application. `VITE_EXAMPLE_EXTENSION=true` appends it, which
  * is how the framework's own extension-point specs get an installed extension to
  * assert against, and how anyone can see it running without editing this file.
+ *
+ * That switch is for the bundled example and nothing else — it names no extension
+ * and cannot. An extension has to be imported to be in the bundle at all, which is
+ * the same reason installing one is an edit here rather than a setting.
  */
 export const activeAppExtensions: readonly AppExtensionConfig[] = [
-  ...(import.meta.env.VITE_APP_EXTENSIONS === "example"
-    ? [exampleAppExtension]
-    : []),
+  ...(import.meta.env.VITE_EXAMPLE_EXTENSION === "true" ? [exampleAppExtension] : []),
 ];

ui/src/vite-env.d.ts

@@ -5,6 +5,14 @@ interface ImportMetaEnv {
   readonly VITE_API_MODE?: "mock" | "live";
   /** Base URL of the real API, used when VITE_API_MODE is "live". */
   readonly VITE_API_BASE_URL?: string;
+  /**
+   * `"true"` installs the bundled Example App Extension.
+   *
+   * A switch for that one config, not a list of extensions to install: an
+   * extension has to be imported to be in the bundle at all, so which ones are
+   * installed is the array in `appExtensions/activeExtensions.ts`.
+   */
+  readonly VITE_EXAMPLE_EXTENSION?: "true" | "false";
 }
 
 interface ImportMeta {