mfeflow 0.0.0-stage → 0.2.0

package/assets/features/event-bus/feature.json

@@ -0,0 +1,100 @@
+{
+  "name": "event-bus",
+  "version": "0.1.0",
+  "description": "Typed events between remotes (@mfeflow/event-bus) and the contracts package that holds their types: packages/contracts/src/events, merged into the bus in every app, with a sample event.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "packages/contracts/package.json",
+      "target": "root",
+      "from": "files/contracts-package.json.eta",
+      "template": true
+    },
+    {
+      "to": "packages/contracts/src/events/index.ts",
+      "target": "root",
+      "from": "files/contracts-events.ts"
+    },
+    {
+      "to": "packages/contracts/README.md",
+      "target": "root",
+      "from": "files/contracts-readme.md"
+    },
+    {
+      "to": "src/events.ts",
+      "target": "shell",
+      "from": "files/shell-events.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/events.test.ts",
+      "target": "shell",
+      "from": "files/shell-events-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/events.ts",
+      "target": "remotes",
+      "from": "files/events.ts.eta",
+      "template": true
+    },
+    {
+      "to": "src/events.test.ts",
+      "target": "remotes",
+      "from": "files/events-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/Announce.tsx",
+      "target": "remotes",
+      "from": "files/announce.tsx.eta",
+      "template": true
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/event-bus",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/event-bus",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "shell"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "configureShellEvents",
+      "from": "./events",
+      "await": false
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/exposed/App.tsx",
+      "target": "remotes",
+      "component": "Announce",
+      "from": "../Announce",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/event-bus/files/announce.tsx.eta

@@ -0,0 +1,10 @@
+import { useEffect, type ReactNode } from 'react';
+import { announceReady } from './events';
+
+/** Tells the other remotes that <%= it.app.name %> is on the page, each time it mounts. */
+export function Announce({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    announceReady();
+  }, []);
+  return <>{children}</>;
+}

package/assets/features/event-bus/files/contracts-events.ts

@@ -0,0 +1,11 @@
+/**
+ * Every event the platform can carry, by versioned name: <domain>.<event>.v<major>, like
+ * cart.item-added.v1. Types only: nothing here runs, so any remote can read it.
+ *
+ * Add an event by adding a line. Change a payload in a way old listeners cannot read by adding
+ * a new version (cart.item-added.v2) and publishing both until every listener has moved.
+ */
+export interface Events {
+  /** A remote is on the page. The sample event: every remote announces itself, every other one can listen. */
+  'mfe.ready.v1': { mfe: string };
+}

package/assets/features/event-bus/files/contracts-package.json.eta

@@ -0,0 +1,10 @@
+{
+  "name": "<%= it.scope %>/contracts",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./events": "./src/events/index.ts",
+    "./routes/*": "./src/routes/*.ts"
+  }
+}

package/assets/features/event-bus/files/contracts-readme.md

@@ -0,0 +1,10 @@
+# contracts
+
+What the micro-frontends agree on, and nothing else. A remote never imports another remote; it
+imports this.
+
+- `src/events`: the events remotes publish and listen to, as types.
+- `src/routes`: each remote's public paths, as plain data (added by `route-factory`).
+
+Keep it to types and plain data with no imports, so reading it costs a remote nothing at run time
+and it never pulls in another remote's code.

package/assets/features/event-bus/files/events-test.ts.eta

@@ -0,0 +1,18 @@
+import { publish, resetEventBusForTests } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { announceReady, onOtherRemoteReady } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the <%= it.app.name %> events', () => {
+  it('hears another remote and not itself', () => {
+    const heard = vi.fn();
+    const stop = onOtherRemoteReady(heard);
+    announceReady();
+    publish('mfe.ready.v1', { mfe: 'somewhere-else' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith('somewhere-else');
+    stop();
+    publish('mfe.ready.v1', { mfe: 'later' });
+    expect(heard).toHaveBeenCalledOnce();
+  });
+});

package/assets/features/event-bus/files/events.ts.eta

@@ -0,0 +1,20 @@
+import { publish, subscribe } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/** Tells the other remotes that <%= it.app.name %> is on the page. */
+export function announceReady(): void {
+  publish('mfe.ready.v1', { mfe: '<%= it.app.name %>' });
+}
+
+/** Calls `handler` with the name of each other remote that announces itself. Returns the function that stops it. */
+export function onOtherRemoteReady(handler: (mfe: string) => void): () => void {
+  return subscribe('mfe.ready.v1', ({ mfe }) => {
+    if (mfe !== '<%= it.app.name %>') handler(mfe);
+  });
+}

package/assets/features/event-bus/files/shell-events-test.ts.eta

@@ -0,0 +1,22 @@
+import { publish, resetEventBusForTests, subscribe } from '@mfeflow/event-bus';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { configureShellEvents } from './events';
+
+afterEach(resetEventBusForTests);
+
+describe('the shell event bus', () => {
+  it('carries the contracts events between remotes', () => {
+    const heard = vi.fn();
+    subscribe('mfe.ready.v1', heard);
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    expect(heard).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+
+  it('replays the latest announcement to a remote that mounts late', () => {
+    configureShellEvents();
+    publish('mfe.ready.v1', { mfe: 'cart' });
+    const late = vi.fn();
+    subscribe('mfe.ready.v1', late);
+    expect(late).toHaveBeenCalledExactlyOnceWith({ mfe: 'cart' });
+  });
+});

package/assets/features/event-bus/files/shell-events.ts.eta

@@ -0,0 +1,19 @@
+import { configureEvent } from '@mfeflow/event-bus';
+import type { Events } from '<%= it.scope %>/contracts/events';
+
+// The platform's event map is the contracts package's. This one declaration merges it in.
+declare module '@mfeflow/event-bus' {
+  // oxlint-disable-next-line typescript/no-empty-interface -- merges the contracts into the platform map
+  interface EventMap extends Events {}
+}
+
+/**
+ * How the platform's events behave, set once at boot. The shell imports the bus here, which makes
+ * it the one that provides the copy every remote shares.
+ */
+export function configureShellEvents(): void {
+  // "This remote is up" is a fact about the page, not a moment: a remote that mounts later still
+  // hears the latest announcement. Only the last one is kept. Leave replay off for events that
+  // are things that happened, like cart.item-added.v1.
+  configureEvent('mfe.ready.v1', { replay: true });
+}

package/assets/features/git-hooks/feature.json

@@ -0,0 +1,42 @@
+{
+  "name": "git-hooks",
+  "version": "0.1.0",
+  "description": "lefthook with commitlint: Conventional Commit messages, typecheck before push. Opt-in.",
+  "requires": ["core"],
+  "files": [
+    {
+      "to": "lefthook.yml",
+      "from": "files/lefthook.yml"
+    },
+    {
+      "to": "commitlint.config.js",
+      "from": "files/commitlint.config.js"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "lefthook",
+      "range": "2.2.2",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@commitlint/cli",
+      "range": "21.2.4",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@commitlint/config-conventional",
+      "range": "21.2.4",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "prepare",
+      "command": "lefthook install"
+    }
+  ]
+}

package/assets/features/git-hooks/files/commitlint.config.js

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/assets/features/git-hooks/files/lefthook.yml

@@ -0,0 +1,9 @@
+commit-msg:
+  commands:
+    commitlint:
+      run: pnpm commitlint --edit {1}
+
+pre-push:
+  commands:
+    typecheck:
+      run: pnpm typecheck

package/assets/features/http/feature.json

@@ -0,0 +1,81 @@
+{
+  "name": "http",
+  "version": "0.1.0",
+  "description": "A fetch client over your url-factory endpoints (@mfeflow/http): src/api/client.ts in every app, with retries for idempotent requests, timeouts and typed errors. The API base URL is the runtime config's apiUrl.",
+  "requires": ["core", "tsconfig", "url-factory"],
+  "files": [
+    {
+      "to": "src/api/client.ts",
+      "target": "shell",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.ts",
+      "target": "remotes",
+      "from": "files/client.ts"
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "shell",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    },
+    {
+      "to": "src/api/client.test.ts",
+      "target": "remotes",
+      "from": "files/client-test.ts",
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "shell"
+    },
+    {
+      "name": "@mfeflow/http",
+      "range": "latest",
+      "target": "remotes"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().min(1)",
+        "valibot": "v.pipe(v.string(), v.minLength(1))",
+        "arktype": "'string > 0'"
+      },
+      "value": "/api",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:env-t3": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "public/config/runtime-config.json",
+      "target": "shell",
+      "key": "apiUrl",
+      "scope": "runtime",
+      "schema": "z.string().min(1)",
+      "value": "/api",
+      "when": {
+        "feature:env-t3": false
+      }
+    }
+  ]
+}

package/assets/features/http/files/client-test.ts

@@ -0,0 +1,19 @@
+import { isHttpError } from '@mfeflow/http';
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+import { server } from '../mocks/server';
+import { api } from './client';
+
+describe('the api client', () => {
+  it('reads an endpoint through the mock server', async () => {
+    expect(await api.get('health')).toEqual({ ok: true });
+  });
+
+  it('turns a failure into an HttpError with the status', async () => {
+    server.use(
+      http.get('*/api/health', () => HttpResponse.json({ error: 'down' }, { status: 404 })),
+    );
+    const error = await api.get('health').catch((e: unknown) => e);
+    expect(isHttpError(error) && error.status).toBe(404);
+  });
+});

package/assets/features/http/files/client.ts

@@ -0,0 +1,20 @@
+import { createHttpClient } from '@mfeflow/http';
+import { apiUrl, type endpoints } from './endpoints';
+
+// What each endpoint answers with, by the name in ./endpoints. Add a line per endpoint you call.
+interface Responses {
+  health: { ok: boolean };
+}
+
+/**
+ * One client per app over the endpoints in ./endpoints. The base URL is the runtime config's
+ * `apiUrl`. Idempotent requests retry on a network error, a timeout and a 502, 503 or 504; a
+ * failure is an HttpError with the status and body, and no URL in its message.
+ *
+ *   const { ok } = await api.get('health');
+ */
+export const api = createHttpClient<typeof endpoints, Responses>({
+  url: apiUrl,
+  // Return the signed-in user's token; no header is sent while this returns undefined.
+  // getToken: () => session.accessToken(),
+});

package/assets/features/lint-oxlint/feature.json

@@ -0,0 +1,60 @@
+{
+  "name": "lint-oxlint",
+  "version": "0.1.0",
+  "description": "oxlint with type-aware rules on TypeScript 7 (@mfeflow/oxlint-config), and Prettier.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": ".oxlintrc.json",
+      "from": "files/oxlintrc.json"
+    },
+    {
+      "to": ".prettierrc.json",
+      "from": "files/prettierrc.json"
+    },
+    {
+      "to": ".prettierignore",
+      "from": "files/prettierignore"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/oxlint-config",
+      "range": "latest",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "oxlint",
+      "range": "1.90.0",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "oxlint-tsgolint",
+      "range": "7.0.2005",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "prettier",
+      "range": "3.9.10",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "lint",
+      "command": "oxlint --type-aware --deny-warnings"
+    },
+    {
+      "name": "format",
+      "command": "prettier --write ."
+    },
+    {
+      "name": "format:check",
+      "command": "prettier --check ."
+    }
+  ]
+}

package/assets/features/lint-oxlint/files/oxlintrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": ["./node_modules/@mfeflow/oxlint-config/oxlintrc.json"],
+  "ignorePatterns": ["**/dist/**", "**/.turbo/**"]
+}

package/assets/features/lint-oxlint/files/prettierignore

@@ -0,0 +1,5 @@
+dist
+.turbo
+coverage
+pnpm-lock.yaml
+CHANGELOG.md

package/assets/features/lint-oxlint/files/prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "printWidth": 100,
+  "overrides": [{ "files": "*.yaml", "options": { "singleQuote": false } }]
+}

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

@@ -0,0 +1,60 @@
+{
+  "name": "route-factory",
+  "version": "0.1.0",
+  "description": "Typed links between remotes (@mfeflow/route-factory): src/routes.ts in every remote. With event-bus the paths live in the contracts package, so remotes link to each other without importing each other.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "src/routes.ts",
+      "target": "remotes",
+      "from": "files/routes.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": false
+      }
+    },
+    {
+      "to": "src/routes.ts",
+      "target": "remotes",
+      "from": "files/routes-contract.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": true
+      }
+    },
+    {
+      "to": "packages/contracts/src/routes/{{app.name}}.ts",
+      "target": "remotes",
+      "atRoot": true,
+      "from": "files/contract.ts.eta",
+      "template": true,
+      "when": {
+        "feature:event-bus": true
+      }
+    },
+    {
+      "to": "src/routes.test.ts",
+      "target": "remotes",
+      "from": "files/routes-test.ts.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@mfeflow/route-factory",
+      "range": "latest",
+      "target": "remotes"
+    },
+    {
+      "name": "{{scope}}/contracts",
+      "range": "workspace:*",
+      "target": "remotes",
+      "when": {
+        "feature:event-bus": true
+      }
+    }
+  ]
+}

package/assets/features/route-factory/files/contract.ts.eta

@@ -0,0 +1,7 @@
+/**
+ * <%= it.app.name %>'s public paths, as plain data: no imports, so any remote can read them.
+ * `:id` is a path param; `?q&page?` after the path names search params (q is required).
+ */
+export const routes = {
+  home: '/',
+} as const;

package/assets/features/route-factory/files/routes-contract.ts.eta

@@ -0,0 +1,11 @@
+import { createLinks, defineRoutes } from '@mfeflow/route-factory';
+import { routes as contract } from '<%= it.scope %>/contracts/routes/<%= it.app.name %>';
+
+// The paths are in the contracts package, so another remote can link here without importing this
+// one. `/<%= it.app.name %>` is where the shell serves this remote.
+export const routes = defineRoutes('/<%= it.app.name %>', contract);
+
+// Links to this remote's routes. Another remote links here with
+//   import { routes as <%= it.app.name %> } from '<%= it.scope %>/contracts/routes/<%= it.app.name %>'
+// and createLinks({ <%= it.app.name %>: defineRoutes('/<%= it.app.name %>', <%= it.app.name %>) }).
+export const links = createLinks({ <%= it.app.name %>: routes });

package/assets/features/route-factory/files/routes-test.ts.eta

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { links, routes } from './routes';
+
+describe('the <%= it.app.name %> routes', () => {
+  it('are served under /<%= it.app.name %>', () => {
+    expect(routes.mount).toBe('/<%= it.app.name %>');
+    expect(links.href('<%= it.app.name %>.home')).toBe('/<%= it.app.name %>');
+  });
+});

package/assets/features/route-factory/files/routes.ts.eta

@@ -0,0 +1,11 @@
+import { createLinks, defineRoutes } from '@mfeflow/route-factory';
+
+// <%= it.app.name %>'s public paths. `/<%= it.app.name %>` is where the shell serves this remote.
+// A route is a path template: `:id` is a path param, and `?q&page?` after the path names search
+// params (q is required, page is optional). Links to a route are checked against this table.
+export const routes = defineRoutes('/<%= it.app.name %>', {
+  home: '/',
+});
+
+// Links to this remote's routes. Another remote links here by adding `{ <%= it.app.name %>: routes }` to its own createLinks.
+export const links = createLinks({ <%= it.app.name %>: routes });