mfeflow 0.0.0-stage → 0.1.0

package/assets/features/testing/files/sample-smoke-e2e.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import { expect, test } from '@playwright/test';
+
+// The remotes the dev registry lists; each one's App carries data-testid="<name>".
+const remotes = fs
+  .readdirSync('registry/envs/dev')
+  .filter((file) => file.endsWith('.json'))
+  .map((file) => file.slice(0, -'.json'.length))
+  .toSorted();
+
+// With env-t3 the shell fetches /config/runtime-config.json at boot and keeps it on globalThis.
+const hasRuntimeConfig = fs.existsSync('scripts/check-runtime-config.ts');
+
+test('the shell loads cleanly, with its runtime config', async ({ page }) => {
+  const problems: string[] = [];
+  page.on('pageerror', (error) => problems.push(`page error: ${error.message}`));
+  page.on('console', (message) => {
+    if (message.type() === 'error') problems.push(`console error: ${message.text()}`);
+  });
+  page.on('requestfailed', (request) =>
+    problems.push(
+      `request failed: ${request.url()} (${request.failure()?.errorText ?? 'unknown'})`,
+    ),
+  );
+  page.on('response', (response) => {
+    if (response.status() >= 400 && !response.url().endsWith('/favicon.ico')) {
+      problems.push(`${String(response.status())} ${response.url()}`);
+    }
+  });
+  await page.goto('/');
+  await expect(page.locator('header')).toBeVisible();
+  if (hasRuntimeConfig) {
+    await expect
+      .poll(() =>
+        page.evaluate(() => {
+          const config: unknown = Reflect.get(globalThis, '__MFE_RUNTIME_CONFIG__');
+          return typeof config === 'object' && config !== null && 'environment' in config
+            ? config.environment
+            : undefined;
+        }),
+      )
+      .toBeTruthy();
+  }
+  await page.waitForLoadState('networkidle');
+  expect(problems).toEqual([]);
+});
+
+for (const name of remotes) {
+  test(`the shell renders ${name}`, async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByTestId(name)).toBeVisible();
+  });
+}

package/assets/features/testing/files/server.ts

@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);

package/assets/features/testing/files/setup.ts

@@ -0,0 +1,18 @@
+import { cleanup } from '@testing-library/react';
+import { resetPlatform } from '@mfeflow/testing';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import { server } from '../mocks/server';
+
+beforeAll(() => {
+  server.listen({ onUnhandledFrame: 'error' });
+});
+
+afterEach(() => {
+  cleanup();
+  resetPlatform();
+  server.resetHandlers();
+});
+
+afterAll(() => {
+  server.close();
+});

package/assets/features/testing/files/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // One copy of React and Testing Library, also when a package like @mfeflow/testing is linked from another folder.
+  resolve: { dedupe: ['react', 'react-dom', '@testing-library/react', '@testing-library/dom'] },
+  test: {
+    environment: 'jsdom',
+    include: ['src/**/*.test.{ts,tsx}'],
+    setupFiles: ['./src/test/setup.ts'],
+  },
+});

package/assets/features/tsconfig/feature.json

@@ -0,0 +1,78 @@
+{
+  "name": "tsconfig",
+  "version": "0.1.0",
+  "description": "Strict TypeScript 7 presets from @mfeflow/tsconfig, and a typecheck script.",
+  "requires": ["core"],
+  "files": [
+    {
+      "to": "tsconfig.json",
+      "target": "shell",
+      "from": "files/tsconfig.json"
+    },
+    {
+      "to": "tsconfig.json",
+      "target": "remotes",
+      "from": "files/tsconfig.json"
+    },
+    {
+      "to": "tsconfig.json",
+      "target": "root",
+      "from": "files/root.tsconfig.json"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/tsconfig",
+      "range": "latest",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@mfeflow/tsconfig",
+      "range": "latest",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@mfeflow/tsconfig",
+      "range": "latest",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "typescript",
+      "range": "7.0.2",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "typescript",
+      "range": "7.0.2",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "typescript",
+      "range": "7.0.2",
+      "target": "remotes",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "typecheck",
+      "command": "turbo run typecheck",
+      "target": "root"
+    },
+    {
+      "name": "typecheck",
+      "command": "tsc --noEmit",
+      "target": "shell"
+    },
+    {
+      "name": "typecheck",
+      "command": "tsc --noEmit",
+      "target": "remotes"
+    }
+  ]
+}

package/assets/features/tsconfig/files/root.tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@mfeflow/tsconfig/node.json",
+  "include": ["*.ts", "scripts", "e2e"]
+}

package/assets/features/tsconfig/files/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@mfeflow/tsconfig/react-app.json",
+  "compilerOptions": { "types": ["node"] },
+  "include": ["src", "rsbuild.config.ts", "env.ts", "vitest.config.ts"]
+}

package/assets/features/url-factory/feature.json

@@ -0,0 +1,30 @@
+{
+  "name": "url-factory",
+  "version": "0.1.0",
+  "description": "Typed endpoint definitions and URL building (@mfeflow/url-factory), src/api/endpoints.ts in every app.",
+  "requires": ["core"],
+  "files": [
+    {
+      "to": "src/api/endpoints.ts",
+      "target": "shell",
+      "from": "files/endpoints.ts"
+    },
+    {
+      "to": "src/api/endpoints.ts",
+      "target": "remotes",
+      "from": "files/endpoints.ts"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/url-factory",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/url-factory",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ]
+}

package/assets/features/url-factory/files/endpoints.ts

@@ -0,0 +1,12 @@
+import { createUrlFactory, defineEndpoints } from '@mfeflow/url-factory';
+
+export const endpoints = defineEndpoints({
+  health: { service: 'api', path: '/health' },
+});
+
+const services: Record<string, string> = { api: '/api' };
+
+export const apiUrl = createUrlFactory(endpoints, (service) => {
+  const base = services[service];
+  return base === undefined ? undefined : new URL(base, location.origin).toString();
+});

package/assets/templates/monorepo/feature.json

@@ -0,0 +1,295 @@
+{
+  "name": "core",
+  "version": "0.1.0",
+  "description": "The shell, the remotes, the registry and the workspace around them.",
+  "files": [
+    {
+      "to": "package.json",
+      "target": "root",
+      "from": "files/root/package.json.eta",
+      "template": true
+    },
+    {
+      "to": "pnpm-workspace.yaml",
+      "target": "root",
+      "from": "files/root/pnpm-workspace.yaml.eta",
+      "template": true
+    },
+    {
+      "to": "turbo.json",
+      "target": "root",
+      "from": "files/root/turbo.json.eta",
+      "template": true
+    },
+    {
+      "to": ".gitignore",
+      "target": "root",
+      "from": "files/root/gitignore.eta",
+      "template": true
+    },
+    {
+      "to": ".nvmrc",
+      "target": "root",
+      "from": "files/root/nvmrc.eta",
+      "template": true
+    },
+    {
+      "to": "README.md",
+      "target": "root",
+      "from": "files/root/README.md.eta",
+      "template": true
+    },
+    {
+      "to": "AGENTS.md",
+      "target": "root",
+      "from": "files/root/AGENTS.md.eta",
+      "template": true
+    },
+    {
+      "to": "registry/envs/dev/.gitkeep",
+      "target": "root",
+      "content": ""
+    },
+    {
+      "to": "registry/envs/staging/.gitkeep",
+      "target": "root",
+      "content": ""
+    },
+    {
+      "to": "registry/envs/prod/.gitkeep",
+      "target": "root",
+      "content": ""
+    },
+    {
+      "to": "package.json",
+      "target": "shell",
+      "from": "files/shell/package.json.eta",
+      "template": true
+    },
+    {
+      "to": "mfe.json",
+      "target": "shell",
+      "from": "files/shell/mfe.json.eta",
+      "template": true
+    },
+    {
+      "to": "rsbuild.config.ts",
+      "target": "shell",
+      "from": "files/shell/rsbuild.config.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/env.d.ts",
+      "target": "shell",
+      "from": "files/shell/src/env.d.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/index.ts",
+      "target": "shell",
+      "from": "files/shell/src/index.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/bootstrap.tsx",
+      "target": "shell",
+      "from": "files/shell/src/bootstrap.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/App.tsx",
+      "target": "shell",
+      "from": "files/shell/src/App.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/remotes/route-table.tsx",
+      "target": "shell",
+      "from": "files/shell/src/remotes/route-table.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "package.json",
+      "target": "remotes",
+      "from": "files/remote/package.json.eta",
+      "template": true
+    },
+    {
+      "to": "mfe.json",
+      "target": "remotes",
+      "from": "files/remote/mfe.json.eta",
+      "template": true
+    },
+    {
+      "to": "rsbuild.config.ts",
+      "target": "remotes",
+      "from": "files/remote/rsbuild.config.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/env.d.ts",
+      "target": "remotes",
+      "from": "files/remote/src/env.d.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/index.ts",
+      "target": "remotes",
+      "from": "files/remote/src/index.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/bootstrap.tsx",
+      "target": "remotes",
+      "from": "files/remote/src/bootstrap.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/exposed/App.tsx",
+      "target": "remotes",
+      "from": "files/remote/src/exposed/App.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/pages/Home.tsx",
+      "target": "shell",
+      "from": "files/shell/src/pages/Home.tsx.eta",
+      "template": true
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "turbo",
+      "range": "2.11.10",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@mfeflow/runtime",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@module-federation/enhanced",
+      "range": "2.9.2",
+      "target": "shell"
+    },
+    {
+      "name": "react",
+      "range": "19.3.1",
+      "target": "shell"
+    },
+    {
+      "name": "react-dom",
+      "range": "19.3.1",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/rsbuild",
+      "range": "latest",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@rsbuild/core",
+      "range": "2.3.0",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@types/node",
+      "range": "26.6.6",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@types/react",
+      "range": "19.3.0",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@types/react-dom",
+      "range": "19.3.0",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@module-federation/enhanced",
+      "range": "2.9.2",
+      "target": "remotes"
+    },
+    {
+      "name": "react",
+      "range": "19.3.1",
+      "target": "remotes"
+    },
+    {
+      "name": "react-dom",
+      "range": "19.3.1",
+      "target": "remotes"
+    },
+    {
+      "name": "@mfeflow/rsbuild",
+      "range": "latest",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@rsbuild/core",
+      "range": "2.3.0",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@types/node",
+      "range": "26.6.6",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@types/react",
+      "range": "19.3.0",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@types/react-dom",
+      "range": "19.3.0",
+      "target": "remotes",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "dev",
+      "command": "turbo run dev",
+      "target": "root"
+    },
+    {
+      "name": "build",
+      "command": "turbo run build",
+      "target": "root"
+    },
+    {
+      "name": "dev",
+      "command": "rsbuild dev",
+      "target": "shell"
+    },
+    {
+      "name": "build",
+      "command": "rsbuild build",
+      "target": "shell"
+    },
+    {
+      "name": "dev",
+      "command": "rsbuild dev",
+      "target": "remotes"
+    },
+    {
+      "name": "build",
+      "command": "rsbuild build",
+      "target": "remotes"
+    }
+  ]
+}

package/assets/templates/monorepo/files/remote/mfe.json.eta

@@ -0,0 +1,7 @@
+{
+  "name": "<%= it.app.name %>",
+  "owner": "team-<%= it.app.name %>",
+  "shells": ["shell"],
+  "routes": ["/<%= it.app.name %>"],
+  "exposes": ["./App"]
+}

package/assets/templates/monorepo/files/remote/package.json.eta

@@ -0,0 +1,6 @@
+{
+  "name": "<%= it.scope %>/<%= it.app.name %>",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module"
+}

package/assets/templates/monorepo/files/remote/rsbuild.config.ts.eta

@@ -0,0 +1,7 @@
+import { createRemoteConfig } from '@mfeflow/rsbuild';
+
+export default createRemoteConfig({
+  name: '<%= it.app.name %>',
+  port: <%= it.app.port %>,
+  exposes: { './App': './src/exposed/App.tsx' },
+});

package/assets/templates/monorepo/files/remote/src/bootstrap.tsx.eta

@@ -0,0 +1,6 @@
+import { createRoot } from 'react-dom/client';
+import App from './exposed/App';
+
+// Standalone mode (`pnpm dev` in this folder). Inside the shell, only ./exposed/* is loaded.
+const el = document.getElementById('root');
+if (el) createRoot(el).render(<App />);

package/assets/templates/monorepo/files/remote/src/env.d.ts.eta

@@ -0,0 +1 @@
+/// <reference types="@rsbuild/core/types" />

package/assets/templates/monorepo/files/remote/src/exposed/App.tsx.eta

@@ -0,0 +1,18 @@
+import { useState } from 'react';
+
+export default function App() {
+  const [clicks, setClicks] = useState(0);
+  return (
+    <section data-testid="<%= it.app.name %>">
+      <h2><%= it.app.name %></h2>
+      <button
+        type="button"
+        onClick={() => {
+          setClicks(clicks + 1);
+        }}
+      >
+        Clicked {clicks} times
+      </button>
+    </section>
+  );
+}

package/assets/templates/monorepo/files/remote/src/index.ts.eta

@@ -0,0 +1,2 @@
+// The async boundary: shared singletons resolve before app code runs.
+void import('./bootstrap');

package/assets/templates/monorepo/files/root/AGENTS.md.eta

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repo.
+
+- Package manager: pnpm (via corepack). Never npm or yarn. Versions live in the `catalog` of
+  `pnpm-workspace.yaml`; add dependencies there and reference them as `catalog:`.
+- `pnpm dev` runs the shell and every remote. `pnpm build` builds all of them. `mfeflow dev` does the same with
+  per-app logs and picks up new remotes without a restart.
+- Before finishing: `mfeflow doctor` (and `mfeflow validate`, `mfeflow check-compat`, `mfeflow budget` after a build) must exit 0.
+- TypeScript 7, strict. Relative imports have no file extension (`./plan`, not `./plan.js`).
+- Each remote is deployed on its own. A remote must not import from another remote or from
+  the shell; talk through the registry, events or URLs.
+- A remote's public surface is `src/exposed/`. Everything else is private to it.
+- Add apps and features with the `mfeflow` CLI (`mfeflow add remote <name>`, `mfeflow features`).
+  `mfeflow.json` is the CLI's record of the project; do not edit the file hashes by hand.
+- Shared singletons (react, react-dom, `@mfeflow/runtime`) are provided by the shell. Do not
+  bundle your own copy.

package/assets/templates/monorepo/files/root/README.md.eta

@@ -0,0 +1,52 @@
+# <%= it.scope.slice(1) %>-platform
+
+A React micro-frontend platform made with [mfeflow](https://github.com/mfeflow/mfeflow):
+one shell and independently deployable remotes, loaded at runtime through Module Federation.
+
+```
+apps/shell      the host: routes, layout, registry loading
+apps/<remote>   one micro-frontend each, exposing ./App
+registry/envs   which build of each remote every environment serves
+mfeflow.json    what the CLI generated; `mfeflow add` reads and updates it
+```
+
+## Run it
+
+```sh
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` starts the shell on http://localhost:4300 and every remote on its own port
+(see `registry/envs/dev`). The shell reads that dev registry and renders the remotes.
+
+`mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
+add a remote with `mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
+Use a remote you already run elsewhere with `mfeflow dev --remote checkout=http://localhost:3001`,
+or run a few apps with `--only shell,catalog`. Ctrl+C stops everything.
+
+## Change it
+
+```sh
+mfeflow add remote checkout     # a new remote, its registry files and its shell route
+mfeflow add <feature>           # see `mfeflow features`
+```
+
+## Check it
+
+```sh
+mfeflow doctor              # singletons, compatibility, config, drift; --fix repairs the safe ones
+mfeflow validate            # mfeflow.json, every mfe.json and every registry entry
+mfeflow check-compat        # each remote's shared ranges against its shell
+mfeflow budget              # after `pnpm build`: first-load JS per shell and remote
+```
+
+All of them take `--json` and exit non-zero on errors, so they can run in CI. `mfeflow budget` checks each remote's entry
+against the 10 KB a remote may add; set `budget.baselineKb` in `mfeflow.json` (your pages built as one app) to check
+the shell against baseline + 32 KB too.
+
+## Before you deploy
+
+`registry/envs/staging` and `registry/envs/prod` point at `example.com`. Replace the hosts
+with where you serve each remote (the shell expects `/mfe/<name>/` on its own origin).
+The shell loads the registry from `/registry/index.json`, so serve one per environment.

package/assets/templates/monorepo/files/root/gitignore.eta

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.turbo/
+coverage/
+*.tsbuildinfo
+.mfeflow/
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store

package/assets/templates/monorepo/files/root/nvmrc.eta

@@ -0,0 +1 @@
+22

package/assets/templates/monorepo/files/root/package.json.eta

@@ -0,0 +1,9 @@
+{
+  "name": "<%= it.scope.slice(1) %>-platform",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@12.16.1",
+  "engines": {
+    "node": ">=22.12"
+  }
+}