mfeflow 0.1.0 → 0.3.0

package/assets/features/i18n/files/remote-I18n-test.tsx.eta

@@ -0,0 +1,43 @@
+import { StrictMode } from 'react';
+import { screen } from '@testing-library/react';
+import { getI18n } from '@mfeflow/i18n';
+import { renderWithPlatform, resetPlatform } from '@mfeflow/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { I18n } from './I18n';
+
+afterEach(resetPlatform);
+
+describe('the <%= it.app.name %> messages', () => {
+  it('start their own i18n when the remote runs without the shell', async () => {
+    renderWithPlatform(
+      <I18n>
+        <p>content</p>
+      </I18n>,
+    );
+    expect(screen.getByText('content')).toBeDefined();
+    expect(await screen.findByText('Hello from <%= it.app.name %>')).toBeDefined();
+  });
+
+  it('follow a language change', async () => {
+    renderWithPlatform(
+      <I18n>
+        <p>content</p>
+      </I18n>,
+    );
+    await screen.findByText('Hello from <%= it.app.name %>');
+    await getI18n().changeLanguage('ar');
+    expect(await screen.findByText('مرحبا من <%= it.app.name %>')).toBeDefined();
+  });
+
+  it('starts one instance when StrictMode runs the effect twice', async () => {
+    renderWithPlatform(
+      <StrictMode>
+        <I18n>
+          <p>content</p>
+        </I18n>
+      </StrictMode>,
+    );
+    expect(await screen.findByText('Hello from <%= it.app.name %>')).toBeDefined();
+    expect(screen.getAllByText('Hello from <%= it.app.name %>')).toHaveLength(1);
+  });
+});

package/assets/features/i18n/files/remote-I18n.tsx.eta

@@ -0,0 +1,36 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { getI18n, initI18n } from '@mfeflow/i18n';
+import { useMfeTranslation } from '@mfeflow/i18n/react';
+import { defaultLanguage, languages } from './config';
+import { loadMessages } from './load';
+
+function started(): boolean {
+  try {
+    getI18n();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function Hello() {
+  const { t } = useMfeTranslation('<%= it.app.name %>', loadMessages);
+  return <p data-testid="<%= it.app.name %>-hello">{t('hello')}</p>;
+}
+
+/** Wraps this remote's App. Inside the shell the page already has an i18n instance; on its own the remote starts one. */
+export function I18n({ children }: { children: ReactNode }) {
+  const [ready, setReady] = useState(started);
+  useEffect(() => {
+    if (ready) return;
+    void initI18n({ languages, defaultLanguage, detect: false }).then(() => {
+      setReady(true);
+    });
+  }, [ready]);
+  return (
+    <>
+      {ready ? <Hello /> : null}
+      {children}
+    </>
+  );
+}

package/assets/features/i18n/files/remote-ar.json.eta

@@ -0,0 +1,3 @@
+{
+  "hello": "مرحبا من <%= it.app.name %>"
+}

package/assets/features/i18n/files/remote-config.ts

@@ -0,0 +1,9 @@
+import type { LanguageOption } from '@mfeflow/i18n';
+
+// Only used when this remote runs on its own (pnpm dev in its folder). Inside the shell, the shell's list wins.
+export const languages: LanguageOption[] = [
+  { code: 'en', label: 'English' },
+  { code: 'ar', label: 'العربية' },
+];
+
+export const defaultLanguage = 'en';

package/assets/features/i18n/files/remote-en.json.eta

@@ -0,0 +1,3 @@
+{
+  "hello": "Hello from <%= it.app.name %>"
+}

package/assets/features/i18n/files/remote-load.ts

@@ -0,0 +1,4 @@
+import type { NamespaceLoader } from '@mfeflow/i18n';
+
+// Each language is its own chunk, served from this remote's deploy and versioned with it.
+export const loadMessages: NamespaceLoader = (language) => import(`./messages/${language}.json`);

package/assets/features/i18n/files/shell-config.ts

@@ -0,0 +1,20 @@
+import type { LanguageOption } from '@mfeflow/i18n';
+
+export const languages: LanguageOption[] = [
+  { code: 'en', label: 'English' },
+  { code: 'ar', label: 'العربية' },
+];
+
+export const defaultLanguage = 'en';
+
+// The shell's own messages ship with the shell. Remotes bring theirs (see their src/i18n folder).
+export const shellMessages: Record<string, { shell: Record<string, string> }> = {
+  en: { shell: { language: 'Language' } },
+  ar: { shell: { language: 'اللغة' } },
+};
+
+/** The messages of one language, or the default language's when this one has none, so the text never goes blank. */
+export function loadShellMessages(language: string): Promise<Record<string, string>> {
+  const found = shellMessages[language] ?? shellMessages[defaultLanguage];
+  return Promise.resolve(found?.shell ?? {});
+}

package/assets/features/i18n/files/shell-init-test.ts

@@ -0,0 +1,32 @@
+import { getI18n, getLanguages } from '@mfeflow/i18n';
+import { resetPlatform } from '@mfeflow/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { loadShellMessages } from './config';
+import { initShellI18n } from './init';
+
+afterEach(resetPlatform);
+
+describe('initShellI18n', () => {
+  it('starts the page instance with the shell languages', async () => {
+    await initShellI18n();
+    expect(getLanguages().map((l) => l.code)).toEqual(['en', 'ar']);
+    expect(getI18n().t('shell:language')).toBe('Language');
+  });
+
+  it('sets lang and dir when the language changes', async () => {
+    await initShellI18n();
+    await getI18n().changeLanguage('ar');
+    expect(document.documentElement.lang).toBe('ar');
+    expect(document.documentElement.dir).toBe('rtl');
+  });
+});
+
+describe('loadShellMessages', () => {
+  it('gives the messages of the language asked for', async () => {
+    expect(await loadShellMessages('ar')).toEqual({ language: 'اللغة' });
+  });
+
+  it('falls back to the default language for one with no messages', async () => {
+    expect(await loadShellMessages('fr')).toEqual({ language: 'Language' });
+  });
+});

package/assets/features/i18n/files/shell-init.ts

@@ -0,0 +1,7 @@
+import { initI18n } from '@mfeflow/i18n';
+import { defaultLanguage, languages, shellMessages } from './config';
+
+/** The boot step: one i18next instance for the page, shared by the shell and every remote. */
+export async function initShellI18n(): Promise<void> {
+  await initI18n({ languages, defaultLanguage, resources: shellMessages });
+}

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

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

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

@@ -1,5 +1,6 @@
 dist
 .turbo
+storybook-static
 coverage
 pnpm-lock.yaml
 CHANGELOG.md

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 });

package/assets/features/storybook/feature.json

@@ -0,0 +1,119 @@
+{
+  "name": "storybook",
+  "version": "0.1.0",
+  "description": "Storybook 10 on Rsbuild (storybook-react-rsbuild) in every remote, and the shell's Storybook shows them all: it lists each remote's built Storybook as a ref, found from mfeflow.json, so a remote added later appears without an edit. Each remote has its own Storybook config, kept apart from the Module Federation build.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": ".storybook/main.ts",
+      "target": "shell",
+      "from": "files/shell-main.ts"
+    },
+    {
+      "to": ".storybook/rsbuild.config.ts",
+      "target": "shell",
+      "from": "files/rsbuild.config.ts"
+    },
+    {
+      "to": "src/pages/Home.stories.tsx",
+      "target": "shell",
+      "from": "files/Home.stories.tsx"
+    },
+    {
+      "to": ".storybook/main.ts",
+      "target": "remotes",
+      "from": "files/remote-main.ts"
+    },
+    {
+      "to": ".storybook/rsbuild.config.ts",
+      "target": "remotes",
+      "from": "files/rsbuild.config.ts"
+    },
+    {
+      "to": "src/exposed/App.stories.tsx",
+      "target": "remotes",
+      "from": "files/App.stories.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/components/ui/button.stories.tsx",
+      "target": "remotes",
+      "from": "files/button.stories.tsx",
+      "when": {
+        "feature:ui-shadcn": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "storybook",
+      "range": "10.6.5",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "storybook-react-rsbuild",
+      "range": "3.6.1",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@rsbuild/plugin-react",
+      "range": "2.1.1",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "storybook",
+      "range": "10.6.5",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "storybook-react-rsbuild",
+      "range": "3.6.1",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@rsbuild/plugin-react",
+      "range": "2.1.1",
+      "target": "remotes",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "storybook",
+      "command": "storybook dev --no-open",
+      "target": "shell"
+    },
+    {
+      "name": "storybook:build",
+      "command": "storybook build -o storybook-static",
+      "target": "shell"
+    },
+    {
+      "name": "storybook",
+      "command": "storybook dev --no-open --ci",
+      "target": "remotes"
+    },
+    {
+      "name": "storybook:build",
+      "command": "storybook build -o storybook-static",
+      "target": "remotes"
+    },
+    {
+      "name": "storybook:remotes",
+      "command": "pnpm --filter \"./apps/*\" --filter \"!./apps/shell\" run --if-present storybook:build"
+    },
+    {
+      "name": "storybook",
+      "command": "pnpm storybook:remotes && pnpm --filter ./apps/shell run storybook"
+    },
+    {
+      "name": "storybook:build",
+      "command": "pnpm storybook:remotes && pnpm --filter ./apps/shell run storybook:build"
+    }
+  ]
+}

package/assets/features/storybook/files/App.stories.tsx.eta

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from 'storybook-react-rsbuild';
+import App from './App';
+
+const meta = { title: '<%= it.app.name %>/App', component: App } satisfies Meta<typeof App>;
+
+export default meta;
+
+export const Default: StoryObj<typeof meta> = {};

package/assets/features/storybook/files/Home.stories.tsx

@@ -0,0 +1,9 @@
+import type { Meta, StoryObj } from 'storybook-react-rsbuild';
+import { Home } from './Home';
+
+const meta = { title: 'shell/Home', component: Home } satisfies Meta<typeof Home>;
+
+export default meta;
+
+// No registry is loaded in Storybook, so this is the empty state.
+export const NoRemotes: StoryObj<typeof meta> = {};

package/assets/features/storybook/files/button.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from 'storybook-react-rsbuild';
+import { Button } from './button';
+
+const meta = {
+  title: 'ui/Button',
+  component: Button,
+  args: { children: 'Save' },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+
+export const Default: StoryObj<typeof meta> = {};
+export const Secondary: StoryObj<typeof meta> = { args: { variant: 'secondary' } };
+export const Destructive: StoryObj<typeof meta> = { args: { variant: 'destructive' } };

package/assets/features/storybook/files/remote-main.ts

@@ -0,0 +1,13 @@
+import type { StorybookConfig } from 'storybook-react-rsbuild';
+
+const config: StorybookConfig = {
+  framework: {
+    name: 'storybook-react-rsbuild',
+    options: { builder: { rsbuildConfigPath: './.storybook/rsbuild.config.ts' } },
+  },
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [],
+  core: { disableTelemetry: true, disableWhatsNewNotifications: true },
+};
+
+export default config;

package/assets/features/storybook/files/rsbuild.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from '@rsbuild/core';
+import { pluginReact } from '@rsbuild/plugin-react';
+
+// Storybook's own build config. It leaves out the app's rsbuild.config.ts on purpose: that one
+// sets up Module Federation, which a story does not need. Add loaders or aliases your stories need here.
+export default defineConfig({
+  plugins: [pluginReact()],
+  // One copy of React, also when a package is linked from another folder.
+  resolve: { dedupe: ['react', 'react-dom'] },
+});

package/assets/features/storybook/files/shell-main.ts

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { StorybookConfig } from 'storybook-react-rsbuild';
+
+// The shell's Storybook shows its own stories and every remote's, each remote as a ref. Remotes are read from
+// mfeflow.json, so one added later appears here without an edit. A ref is the remote's Storybook as built by
+// `pnpm storybook:build` (apps/<remote>/storybook-static), served from /<remote>/ inside this one.
+const root = path.resolve(import.meta.dirname, '../../..');
+
+function field(value: unknown, key: string): unknown {
+  return typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined;
+}
+
+function remoteStorybooks(): { name: string; built: string }[] {
+  const apps = field(JSON.parse(fs.readFileSync(path.join(root, 'mfeflow.json'), 'utf8')), 'apps');
+  if (typeof apps !== 'object' || apps === null) return [];
+  return Object.entries(apps).flatMap(([name, app]) => {
+    const dir = field(app, 'path');
+    if (field(app, 'kind') !== 'remote' || typeof dir !== 'string') return [];
+    const built = path.join(root, dir, 'storybook-static');
+    return fs.existsSync(path.join(built, 'index.json')) ? [{ name, built }] : [];
+  });
+}
+
+const remotes = remoteStorybooks();
+
+const config: StorybookConfig = {
+  framework: {
+    name: 'storybook-react-rsbuild',
+    options: { builder: { rsbuildConfigPath: './.storybook/rsbuild.config.ts' } },
+  },
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [],
+  core: { disableTelemetry: true, disableWhatsNewNotifications: true },
+  staticDirs: remotes.map(({ name, built }) => ({ from: built, to: `/${name}` })),
+  refs: Object.fromEntries(remotes.map(({ name }) => [name, { title: name, url: `./${name}` }])),
+};
+
+export default config;

package/assets/features/tailwind/feature.json

@@ -0,0 +1,87 @@
+{
+  "name": "tailwind",
+  "version": "0.1.0",
+  "description": "Tailwind CSS 4 through PostCSS. The shell loads Tailwind's reset (preflight) once; every app gets its own class prefix (cart:flex), so two remotes using the same utility with different tokens never collide. The colour tokens read the --mf-* theme variables, with fallbacks, so they follow theming whichever way round the two are added.",
+  "requires": ["core", "tsconfig"],
+  "files": [
+    {
+      "to": "postcss.config.mjs",
+      "target": "shell",
+      "from": "files/postcss.config.mjs"
+    },
+    {
+      "to": "src/styles.css",
+      "target": "shell",
+      "from": "files/shell-styles.css.eta",
+      "template": true
+    },
+    {
+      "to": "postcss.config.mjs",
+      "target": "remotes",
+      "from": "files/postcss.config.mjs"
+    },
+    {
+      "to": "src/styles.css",
+      "target": "remotes",
+      "from": "files/remote-styles.css.eta",
+      "template": true
+    },
+    {
+      "to": "src/tailwind/Scope.tsx",
+      "target": "remotes",
+      "from": "files/Scope.tsx.eta",
+      "template": true
+    },
+    {
+      "to": "src/tailwind/Scope.test.tsx",
+      "target": "remotes",
+      "from": "files/Scope-test.tsx.eta",
+      "template": true,
+      "when": {
+        "feature:testing": true
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "tailwindcss",
+      "range": "4.3.3",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@tailwindcss/postcss",
+      "range": "4.3.3",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "tailwindcss",
+      "range": "4.3.3",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "@tailwindcss/postcss",
+      "range": "4.3.3",
+      "target": "remotes",
+      "dev": true
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-import",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "from": "./styles.css"
+    },
+    {
+      "op": "wrap-provider",
+      "file": "src/exposed/App.tsx",
+      "target": "remotes",
+      "component": "Scope",
+      "from": "../tailwind/Scope",
+      "function": "App"
+    }
+  ]
+}

package/assets/features/tailwind/files/Scope-test.tsx.eta

@@ -0,0 +1,17 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { Scope } from './Scope';
+
+describe('the <%= it.app.name %> Tailwind scope', () => {
+  it('prefixes every class with this remote', () => {
+    render(
+      <Scope>
+        <p>content</p>
+      </Scope>,
+    );
+    const root = screen.getByText('content').parentElement;
+    for (const name of (root?.className ?? '').split(' ')) {
+      expect(name.includes(':'), name).toBe(true);
+    }
+  });
+});

package/assets/features/tailwind/files/Scope.tsx.eta

@@ -0,0 +1,15 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+import type { ReactNode } from 'react';
+import '../styles.css';
+
+// prettier-ignore
+const classes = '<%= prefix %>:p-2 <%= prefix %>:outline-2 <%= prefix %>:outline-primary';
+
+/** Wraps this remote's App and loads its styles. The outline shows the primary token; delete it when you have your own markup. */
+export function Scope({ children }: { children: ReactNode }) {
+  return (
+    <div data-tailwind="<%= it.app.name %>" className={classes}>
+      {children}
+    </div>
+  );
+}

package/assets/features/tailwind/files/postcss.config.mjs

@@ -0,0 +1 @@
+export default { plugins: { '@tailwindcss/postcss': {} } };

package/assets/features/tailwind/files/remote-styles.css.eta

@@ -0,0 +1,21 @@
+<%_ const prefix = it.app.tailwindPrefix _%>
+/* No reset here: the shell has it. Classes are written <%= prefix %>:flex, and the theme variables are --<%= prefix %>-*. */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme) prefix(<%= prefix %>);
+@import 'tailwindcss/utilities.css' layer(utilities) prefix(<%= prefix %>);
+
+/* Tokens read the theme variables (--mf-*). The second value is used when there is no theme. */
+@theme inline {
+  --color-background: var(--mf-color-bg, #ffffff);
+  --color-foreground: var(--mf-color-fg, #111827);
+  --color-surface: var(--mf-color-surface, #f3f4f6);
+  --color-primary: var(--mf-color-primary, #2563eb);
+  --color-primary-foreground: var(--mf-color-primary-fg, #ffffff);
+  --color-secondary: var(--mf-color-surface, #f3f4f6);
+  --color-secondary-foreground: var(--mf-color-fg, #111827);
+  --color-accent: var(--mf-color-surface, #f3f4f6);
+  --color-accent-foreground: var(--mf-color-fg, #111827);
+  --color-destructive: #dc2626;
+  --color-border: var(--mf-color-border, #e5e7eb);
+  --color-ring: var(--mf-color-primary, #2563eb);
+}