mfeflow 0.0.0-stage → 0.2.0

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,23 @@
+import { createUrlFactory, defineEndpoints } from '@mfeflow/url-factory';
+
+export const endpoints = defineEndpoints({
+  health: { service: 'api', path: '/health' },
+});
+
+const defaults: Record<string, string> = { api: '/api' };
+
+// A service's base is `<service>Url` in the runtime config (apiUrl for api) when the shell loaded
+// one, so a build runs in every environment; the default above is for tests and standalone runs.
+function configured(service: string): string | undefined {
+  const config: unknown = Reflect.get(globalThis, '__MFE_RUNTIME_CONFIG__');
+  const value: unknown =
+    typeof config === 'object' && config !== null
+      ? Reflect.get(config, `${service}Url`)
+      : undefined;
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+export const apiUrl = createUrlFactory(endpoints, (service) => {
+  const base = configured(service) ?? defaults[service];
+  return base === undefined ? undefined : new URL(base, location.origin).toString();
+});

package/assets/templates/monorepo/feature.json

@@ -0,0 +1,321 @@
+{
+  "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",
+      "range": "latest",
+      "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": "doctor",
+      "command": "mfeflow doctor",
+      "target": "root"
+    },
+    {
+      "name": "validate",
+      "command": "mfeflow validate",
+      "target": "root"
+    },
+    {
+      "name": "check-compat",
+      "command": "mfeflow check-compat",
+      "target": "root"
+    },
+    {
+      "name": "budget",
+      "command": "mfeflow budget",
+      "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. `pnpm mfeflow dev` does the same with
+  per-app logs and picks up new remotes without a restart.
+- Before finishing: `pnpm doctor` (and `pnpm validate`, `pnpm check-compat`, `pnpm 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, installed as a root dev dependency (`pnpm mfeflow add remote <name>`, `pnpm 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; `pnpm 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.
+
+`pnpm mfeflow dev` does the same with a prefixed, coloured log per app, and it follows the project:
+add a remote with `pnpm mfeflow add remote checkout` and it starts, and the shell lists it, without a restart.
+Use a remote you already run elsewhere with `pnpm mfeflow dev --remote checkout=http://localhost:3001`,
+or run a few apps with `--only shell,catalog`. Ctrl+C stops everything.
+
+## Change it
+
+```sh
+pnpm mfeflow add remote checkout     # a new remote, its registry files and its shell route
+pnpm mfeflow add <feature>           # see `pnpm mfeflow features`
+```
+
+## Check it
+
+```sh
+pnpm doctor              # singletons, compatibility, config, drift; `pnpm doctor --fix` repairs the safe ones
+pnpm validate            # mfeflow.json, every mfe.json and every registry entry
+pnpm check-compat        # each remote's shared ranges against its shell
+pnpm budget              # after `pnpm build`: first-load JS per shell and remote
+```
+
+Each is a root script for the `mfeflow` CLI in your devDependencies (`pnpm mfeflow <command>` runs it directly). All of them take `--json` and exit non-zero on errors, so they can run in CI. `pnpm 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"
+  }
+}

package/assets/templates/monorepo/files/root/pnpm-workspace.yaml.eta

@@ -0,0 +1,7 @@
+packages:
+  - apps/*
+  - packages/*
+
+# Dependencies allowed to run install scripts.
+allowBuilds:
+  lefthook: true

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}

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

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

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

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