@mfeflow/route-factory 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @mfeflow/route-factory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed links between micro-frontends. Each remote defines its routes once; a link to any of them is checked at compile time for a missing param, a missing search param and an unknown route.
+
+## Install
+
+```sh
+pnpm add @mfeflow/route-factory
+```
+
+`react` (19) is an optional peer dependency, needed only for `@mfeflow/route-factory/react`. In a project made with mfeflow, `mfeflow add route-factory` does all of this.
+
+## Usage
+
+```ts
+import { createLinks, defineRoutes } from '@mfeflow/route-factory';
+
+// `/catalog` is where the shell serves the remote. `?q&page?` names search params: q is required.
+export const catalogRoutes = defineRoutes('/catalog', {
+  home: '/',
+  product: '/products/:sku',
+  search: '/search?q&page?',
+});
+export const cartRoutes = defineRoutes('/cart', { home: '/' });
+
+const links = createLinks({ catalog: catalogRoutes, cart: cartRoutes }, { base: '/app' });
+
+links.href('catalog.product', { params: { sku: 'A1' } }); // /app/catalog/products/A1
+links.href('catalog.search', { search: { q: 'red mug' }, hash: 'top' }); // /app/catalog/search?q=red+mug#top
+links.href('catalog.product'); // compile error: sku is missing
+links.href('catalog.checkout'); // compile error: no such route
+```
+
+The route definitions are plain strings, so they can sit in a contracts package that other remotes read without importing the remote. `links.path` gives the same URL without `base`, for a router that has its own `basename`.
+
+`base` can be a function, read on every call, so it may come from runtime config that loads later.
+
+### The shell's route table
+
+```ts
+import { shellRoutes } from '@mfeflow/route-factory';
+shellRoutes({ catalog: catalogRoutes, cart: cartRoutes });
+// [{ remote: 'catalog', mount: '/catalog', pattern: '/catalog/*' }, ...]
+```
+
+Use `pattern` in a router or in `mfe.json` `routes`, `mount` in a hand-written route table.
+
+### React
+
+```tsx
+import { createMfeLink } from '@mfeflow/route-factory/react';
+
+const MfeLink = createMfeLink(links); // or createMfeLink(links, { useNavigate }) with React Router
+<MfeLink to="catalog.product" params={{ sku: 'A1' }}>
+  Mug
+</MfeLink>;
+```
+
+There is no dependency on a router. Without `useNavigate`, a left click on a same-origin link pushes the URL and sends `popstate`; modified clicks, middle clicks and `target="_blank"` keep the browser's behaviour.
+
+## Module Federation sharing
+
+Bucket: **stateless**. Nothing here holds state shared between micro-frontends, so each remote can bundle its own copy and different versions can run side by side. No sharing config is needed.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import type { LinkArgs, LinkId, RouteSet, RouteSets, RouteTable, TemplateOf } from './types.js';
+export type { LinkArgs, LinkId, LinkOptions, OptionalSearch, ParamValue, PathParams, RequiredSearch, RouteSet, RouteSets, RouteTable, SearchValue, TemplateOf, } from './types.js';
+/**
+ * One remote's routes. `mount` is where the shell serves the remote (`'/catalog'`, or `'/'` for a
+ * remote at the root); each route is a path under it, with search params after a `?`:
+ *
+ * ```ts
+ * export const catalogRoutes = defineRoutes('/catalog', {
+ *   home: '/',
+ *   product: '/products/:sku',
+ *   search: '/search?q&page?', // q is required, page is optional
+ * });
+ * ```
+ */
+export declare function defineRoutes<const R extends RouteTable>(mount: string, routes: R): RouteSet<R>;
+export interface LinkConfig {
+    /**
+     * Where the shell is served: `''` (default) at the origin's root, `'/app'` under a path, or a
+     * full URL for links that leave the page. A function is read on every call, so it can come from
+     * runtime config that loads after the links are created.
+     */
+    base?: string | (() => string);
+}
+export interface Links<S extends RouteSets> {
+    /** The URL for a route, under the shell's base: `/app/catalog/products/42?ref=home#reviews`. */
+    href: <Id extends LinkId<S>>(id: Id, ...args: LinkArgs<TemplateOf<S, Id>>) => string;
+    /** The same without the base, for a router that has its own `basename`. */
+    path: <Id extends LinkId<S>>(id: Id, ...args: LinkArgs<TemplateOf<S, Id>>) => string;
+}
+/**
+ * Typed links across remotes. The id is `<remote>.<route>`; a missing param, a missing required
+ * search param or an unknown route fails typecheck, and throws if types were bypassed.
+ *
+ * ```ts
+ * const links = createLinks({ catalog: catalogRoutes, cart: cartRoutes }, { base: '/app' });
+ * links.href('catalog.product', { params: { sku: 'A1' }, search: { ref: 'home' } });
+ * ```
+ */
+export declare function createLinks<const S extends RouteSets>(sets: S, config?: LinkConfig): Links<S>;
+/** One line of the shell's route table. */
+export interface ShellRoute {
+    remote: string;
+    /** Where the shell serves the remote, e.g. `/catalog`. */
+    mount: string;
+    /** The same as a wildcard pattern for a router or `mfe.json`, e.g. `/catalog/*`. */
+    pattern: string;
+}
+/**
+ * What the shell needs to route to each remote, from the same definitions the links come from:
+ * add `pattern` to a router or to `mfe.json` `routes`, and `mount` to a hand-written route table.
+ */
+export declare function shellRoutes(sets: RouteSets): ShellRoute[];

package/dist/index.js

@@ -0,0 +1,62 @@
+import { fillPath } from "@mfeflow/url-factory";
+const MOUNT = /^\/([A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*)?$/;
+function defineRoutes(mount, routes) {
+    if (!MOUNT.test(mount)) throw new Error(`route-factory: mount "${mount}" must start with "/" and have no trailing "/", "?" or ":"`);
+    for (const [name, template] of Object.entries(routes))if (!template.startsWith('/')) throw new Error(`route-factory: route "${name}" must start with "/" (got "${template}")`);
+    return {
+        mount: '/' === mount ? '' : mount,
+        routes
+    };
+}
+function trimEnd(base) {
+    return base.endsWith('/') ? base.slice(0, -1) : base;
+}
+function query(search, allowed, id) {
+    const entries = Object.entries(search ?? {}).filter(([, value])=>void 0 !== value);
+    for (const [key] of entries)if (!allowed.includes(key)) throw new Error(`route-factory: "${key}" is not a search param of "${id}"`);
+    if (0 === entries.length) return '';
+    const out = new URLSearchParams();
+    for (const [key, value] of entries)out.append(key, String(value));
+    return `?${out.toString()}`;
+}
+function split(template) {
+    const at = template.indexOf('?');
+    if (-1 === at) return {
+        path: template,
+        search: []
+    };
+    return {
+        path: template.slice(0, at),
+        search: template.slice(at + 1).split('&').filter((part)=>'' !== part).map((part)=>({
+                name: part.replace(/\?$/, ''),
+                required: !part.endsWith('?')
+            }))
+    };
+}
+function createLinks(sets, config = {}) {
+    const build = (withBase)=>(id, options)=>{
+            const dot = id.indexOf('.');
+            const set = sets[id.slice(0, dot)];
+            const template = set?.routes[id.slice(dot + 1)];
+            if (void 0 === set || void 0 === template) throw new Error(`route-factory: unknown route "${id}"`);
+            const { path, search } = split(template);
+            const base = withBase ? trimEnd('function' == typeof config.base ? config.base() : config.base ?? '') : '';
+            const inner = fillPath(path, options?.params, 'route-factory', id);
+            const joined = `${base}${set.mount}${'/' === inner && '' !== set.mount ? '' : inner}`;
+            for (const { name, required } of search)if (required && options?.search?.[name] === void 0) throw new Error(`route-factory: missing search param "${name}" for "${id}"`);
+            const hash = options?.hash ? `#${options.hash.replace(/^#/, '')}` : '';
+            return `${'' === joined ? '/' : joined}${query(options?.search, search.map((s)=>s.name), id)}${hash}`;
+        };
+    return {
+        href: build(true),
+        path: build(false)
+    };
+}
+function shellRoutes(sets) {
+    return Object.entries(sets).map(([remote, set])=>({
+            remote,
+            mount: '' === set.mount ? '/' : set.mount,
+            pattern: `${set.mount}/*`
+        }));
+}
+export { createLinks, defineRoutes, shellRoutes };

package/dist/react.d.ts

@@ -0,0 +1,28 @@
+import type { AnchorHTMLAttributes, ReactElement } from 'react';
+import type { Links } from './index.js';
+import type { LinkId, LinkOptions, RouteSets, TemplateOf } from './types.js';
+export type MfeLinkProps<S extends RouteSets, Id extends LinkId<S>> = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
+    to: Id;
+} & LinkOptions<TemplateOf<S, Id>>;
+export interface MfeLinkConfig {
+    /**
+     * A hook that returns the router's navigate function, taking a path without the base:
+     * `createMfeLink(links, { useNavigate })` with React Router. Without it, a click on a link
+     * to this origin pushes the URL and sends `popstate`, which routers that listen to the
+     * history pick up (single-spa does the same); other links load the page.
+     */
+    useNavigate?: () => (path: string) => void;
+}
+/** Moves to `path` without a page load, and tells whoever listens to the history. */
+export declare function pushPath(path: string): void;
+/**
+ * An `<a>` that links to a route of any remote, typed from the same definitions as `createLinks`.
+ * Left clicks navigate without a page load; middle clicks, modified clicks and `target="_blank"`
+ * keep the browser's behaviour.
+ *
+ * ```tsx
+ * const MfeLink = createMfeLink(links);
+ * <MfeLink to="catalog.product" params={{ sku: 'A1' }}>Mugs</MfeLink>
+ * ```
+ */
+export declare function createMfeLink<S extends RouteSets>(links: Links<S>, config?: MfeLinkConfig): <Id extends LinkId<S>>(props: MfeLinkProps<S, Id>) => ReactElement;

package/dist/react.js

@@ -0,0 +1,39 @@
+import { jsx } from "react/jsx-runtime";
+function pushPath(path) {
+    history.pushState(null, '', path);
+    dispatchEvent(new PopStateEvent('popstate', {
+        state: null
+    }));
+}
+const opensElsewhere = (event, target)=>0 !== event.button || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || void 0 !== target && '_self' !== target;
+function createMfeLink(links, config = {}) {
+    const useRouterNavigate = config.useNavigate ?? (()=>void 0);
+    const href = links.href;
+    const path = links.path;
+    return function({ to, params, search, hash, onClick, children, ...rest }) {
+        const navigate = useRouterNavigate();
+        const options = {
+            params,
+            search,
+            hash
+        };
+        const url = href(to, options);
+        return /*#__PURE__*/ jsx("a", {
+            ...rest,
+            href: url,
+            onClick: (event)=>{
+                onClick?.(event);
+                if (event.defaultPrevented || opensElsewhere(event, rest.target)) return;
+                if (navigate) {
+                    event.preventDefault();
+                    navigate(path(to, options));
+                } else if (new URL(url, location.href).origin === location.origin) {
+                    event.preventDefault();
+                    pushPath(url);
+                }
+            },
+            children: children
+        });
+    };
+}
+export { createMfeLink, pushPath };

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import type { PathParams } from '@mfeflow/url-factory';
+export type { PathParams };
+type PathOf<T extends string> = T extends `${infer Path}?${string}` ? Path : T;
+type QueryOf<T extends string> = T extends `${string}?${infer Query}` ? Query : never;
+type QueryKeys<Q extends string> = Q extends `${infer Head}&${infer Rest}` ? Head | QueryKeys<Rest> : Q;
+/** Search params a template names after `?`: `'/search?q&page?'` has required `q` and optional `page`. */
+export type RequiredSearch<T extends string> = Exclude<QueryKeys<QueryOf<T>>, `${string}?`>;
+export type OptionalSearch<T extends string> = Extract<QueryKeys<QueryOf<T>>, `${string}?`> extends `${infer Key}?` ? Key : never;
+export type ParamValue = string | number;
+export type SearchValue = string | number | boolean;
+type Obj<K extends string, V> = {
+    readonly [P in K]: V;
+};
+/** What a link to a route needs: its path params, its required search params, and optional extras. */
+export type LinkOptions<T extends string> = (PathParams<PathOf<T>> extends never ? {
+    params?: undefined;
+} : {
+    params: Obj<PathParams<PathOf<T>>, ParamValue>;
+}) & (RequiredSearch<T> extends never ? {
+    search?: Partial<Obj<OptionalSearch<T>, SearchValue | undefined>>;
+} : {
+    search: Obj<RequiredSearch<T>, SearchValue> & Partial<Obj<OptionalSearch<T>, SearchValue | undefined>>;
+}) & {
+    hash?: string;
+};
+type NeedsOptions<T extends string> = [PathParams<PathOf<T>> | RequiredSearch<T>] extends [never] ? false : true;
+/** `[options?]` for a route with nothing required, `[options]` otherwise. */
+export type LinkArgs<T extends string> = NeedsOptions<T> extends true ? [options: LinkOptions<T>] : [options?: LinkOptions<T>];
+/** A route is a path template, optionally followed by `?` and its search params. */
+export type RouteTable = Readonly<Record<string, string>>;
+/** One remote's routes: where the shell mounts it and the paths inside. */
+export interface RouteSet<R extends RouteTable = RouteTable> {
+    readonly mount: string;
+    readonly routes: R;
+}
+export type RouteSets = Readonly<Record<string, RouteSet>>;
+/** `catalog.product`: the remote's name, a dot, the route's name. */
+export type LinkId<S extends RouteSets> = {
+    [Remote in keyof S & string]: `${Remote}.${keyof S[Remote]['routes'] & string}`;
+}[keyof S & string];
+export type TemplateOf<S extends RouteSets, Id extends string> = Id extends `${infer Remote}.${infer Name}` ? Remote extends keyof S ? Name extends keyof S[Remote]['routes'] ? S[Remote]['routes'][Name] & string : never : never : never;

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@mfeflow/route-factory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Typed links between micro-frontends: each remote defines its routes once, and a link to any of them is checked for missing params, missing search params and unknown routes at compile time.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "routing",
+    "links",
+    "typescript",
+    "react"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/route-factory"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mfeflow/url-factory": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "stateless"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }