@mfeflow/contracts 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,15 @@
-# Temporary Holding Version
+# @mfeflow/contracts
 
-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.
+Part of [mfeflow](https://github.com/mfeflow/mfeflow), the React micro-frontend boilerplate and platform kit.
+
+Types, validators and JSON Schemas for `mfe.json`, `mfeflow.json` and the remote registry. Pre-1.0: minor versions may change the API.
+
+```sh
+pnpm add @mfeflow/contracts
+```
+
+Bucket: **stateless**. Pure types and functions; no sharing config is needed.
+
+Docs: [mfeflow.github.io/mfeflow](https://mfeflow.github.io/mfeflow/).
+
+MIT licensed.

package/dist/cost-model.d.ts

@@ -0,0 +1,48 @@
+/** What federating costs on one route, against the same pages built as one app. */
+export interface CostModel {
+    /** Largest contentful paint the shell may add, in milliseconds. */
+    lcpDeltaMs: number;
+    /** JS the shell adds over the one-app build, in KB (1 KB = 1024 bytes). */
+    shellKb: number;
+    /** JS each remote on the route adds, in KB. */
+    remoteKb: number;
+}
+export declare const COST_MODEL: CostModel;
+export interface CostSample {
+    /** Bytes of script the shell page loads from its own files (not `/mfe/<name>/`). */
+    shellBytes: number;
+    /** Bytes of script the one-app build loads on the same route. */
+    monolithBytes: number;
+    /** Bytes of script each remote on the route loads. */
+    remoteBytes: Record<string, number>;
+    lcpDeltaMs: number;
+}
+export interface CostLine {
+    budget: number;
+    actual: number;
+    pass: boolean;
+}
+export interface CostVerdict {
+    pass: boolean;
+    lcp: CostLine;
+    shell: CostLine;
+    remotes: (CostLine & {
+        name: string;
+    })[];
+}
+/** Rounds to one decimal, the precision sizes are judged and shown at. */
+export declare const round1: (value: number) => number;
+/** Judges one measured route against the cost model. Sizes come back in KB, one decimal. */
+export declare function judgeCost(sample: CostSample, model?: CostModel): CostVerdict;
+/**
+ * Splits the scripts a shell page loaded into the shell's own and each remote's, by where
+ * they were served from: remotes live under `/mfe/<name>/` on the shell's origin.
+ */
+export declare function splitScripts(requests: readonly {
+    path: string;
+    type: string;
+    bytes: number;
+}[]): {
+    shellBytes: number;
+    remoteBytes: Record<string, number>;
+};

package/dist/docs.d.ts

@@ -0,0 +1,13 @@
+/** Where the documentation site lives. The Rspress `base`, sitemap and llms.txt origin all derive from it. */
+export declare const DOCS_URL = "https://mfeflow.github.io/mfeflow";
+/** Where the JSON Schemas are published, for `$schema` in editors. */
+export declare const SCHEMA_URLS: {
+    readonly mfe: "https://mfeflow.github.io/mfeflow/schema/mfe.json";
+    readonly project: "https://mfeflow.github.io/mfeflow/schema/mfeflow.json";
+    readonly feature: "https://mfeflow.github.io/mfeflow/schema/feature.json";
+    readonly registryEntry: "https://mfeflow.github.io/mfeflow/schema/registry-entry.json";
+    readonly registryIndex: "https://mfeflow.github.io/mfeflow/schema/registry-index.json";
+};
+export type SchemaName = keyof typeof SCHEMA_URLS;
+/** The docs page for an error code such as `E102`. */
+export declare function errorDocsUrl(code: string): string;

package/dist/entry.d.ts

@@ -0,0 +1,11 @@
+/** The remote entry types Module Federation loads (`RemoteEntryType` in its sdk, plus `esm`). */
+export declare const ENTRY_TYPES: readonly string[];
+/**
+ * A global Module Federation can name a remote entry's container: a JS-style identifier that may
+ * also hold `-`, as the `globalName` in `mf-manifest.json` does for a remote like `my-app`.
+ */
+export declare const GLOBAL_NAME: RegExp;
+/** The registry remote fields the shell and the edge read; everything else is dropped. */
+export declare const REGISTRY_REMOTE_FIELDS: readonly string[];
+/** A copy of `remote` with only the whitelisted fields that are set. */
+export declare function pickRegistryFields<T extends object>(remote: T): T;

package/dist/entry.js

@@ -0,0 +1,38 @@
+const ENTRY_TYPES = [
+    'var',
+    'module',
+    'esm',
+    'assign',
+    'assign-properties',
+    'this',
+    'window',
+    'self',
+    'global',
+    'commonjs',
+    'commonjs2',
+    'commonjs-module',
+    'commonjs-static',
+    'amd',
+    'amd-require',
+    'umd',
+    'umd2',
+    'jsonp',
+    'system'
+];
+const GLOBAL_NAME = /^[A-Za-z_$][\w$-]*$/;
+const REGISTRY_REMOTE_FIELDS = [
+    'name',
+    'entry',
+    'remoteEntry',
+    'type',
+    'entryGlobalName',
+    'version',
+    'owner',
+    'routes'
+];
+function pickRegistryFields(remote) {
+    const out = {};
+    for (const [key, value] of Object.entries(remote))if (void 0 !== value && REGISTRY_REMOTE_FIELDS.includes(key)) out[key] = value;
+    return out;
+}
+export { ENTRY_TYPES, GLOBAL_NAME, REGISTRY_REMOTE_FIELDS, pickRegistryFields };

package/dist/feature.d.ts

@@ -0,0 +1,186 @@
+import { type Issue } from './validate.js';
+/** The built-in transform ops. A public, versioned API (decision 0005). */
+export declare const TRANSFORM_OPS: readonly ['add-import', 'wrap-provider', 'add-shared', 'add-boot-step', 'add-env-key', 'add-route', 'add-workflow-step'];
+export type TransformOpName = (typeof TRANSFORM_OPS)[number];
+/** Where a feature part lands: the project root, the shell, every remote, or one app. */
+export type FeatureTarget = string;
+export type PromptValue = string | boolean;
+/**
+ * Applies a part only when every entry holds. A plain name is one of the feature's own options and
+ * must have this value, for example `{ "validator": "zod" }`. `feature:<name>` asks whether that
+ * feature is installed (or being added in the same command), for example `{ "feature:env-t3": true }`.
+ */
+export type FeatureCondition = Record<string, PromptValue>;
+/** The validators `add-env-key` can write a schema for. */
+export type EnvValidator = 'zod' | 'valibot' | 'arktype';
+export interface FeaturePrompt {
+    name: string;
+    type: 'boolean' | 'string' | 'select';
+    message?: string;
+    default?: PromptValue;
+    choices?: string[];
+}
+export interface FeatureFile {
+    /**
+     * Destination, relative to the target. `{{app.name}}` and the other template values are filled
+     * in per app, so a feature can write one file for each remote.
+     */
+    to: string;
+    target?: FeatureTarget;
+    /**
+     * Resolve `to` from the project root instead of the target app, for a file about the app that
+     * lives elsewhere, like `packages/contracts/src/routes/{{app.name}}.ts`. First-party only.
+     */
+    atRoot?: boolean;
+    when?: FeatureCondition;
+    /** Source file inside a local feature folder. Remote features cannot use it. */
+    from?: string;
+    /** Inline content. The only source a remote feature may use. */
+    content?: string;
+    /** Render with eta (local features) or `{{option}}` substitution (remote features). */
+    template?: boolean;
+}
+export interface FeatureDependency {
+    /** An npm package name. `{{scope}}/contracts` is the project's own package of that name. */
+    name: string;
+    range: string;
+    dev?: boolean;
+    target?: FeatureTarget;
+    when?: FeatureCondition;
+}
+export interface FeatureScript {
+    name: string;
+    command: string;
+    target?: FeatureTarget;
+    when?: FeatureCondition;
+}
+export type Literal = string | number | boolean | null;
+interface TransformBase {
+    /** File to edit, relative to the target. */
+    file: string;
+    target?: FeatureTarget;
+    when?: FeatureCondition;
+}
+export interface AddImportOp extends TransformBase {
+    op: 'add-import';
+    from: string;
+    named?: string[];
+    default?: string;
+    namespace?: string;
+    typeOnly?: boolean;
+}
+export interface WrapProviderOp extends TransformBase {
+    op: 'wrap-provider';
+    component: string;
+    from: string;
+    props?: Record<string, Literal>;
+    /** Import `component` as the default export of `from`. Default: a named import. */
+    defaultImport?: boolean;
+    /** The component to wrap the output of. Defaults to `Providers`. */
+    function?: string;
+}
+export interface AddSharedOp extends TransformBase {
+    op: 'add-shared';
+    name: string;
+    /** Name of the array holding the singletons. Defaults to `singletons`. */
+    list?: string;
+}
+export interface AddBootStepOp extends TransformBase {
+    op: 'add-boot-step';
+    call: string;
+    from: string;
+    args?: Literal[];
+    await?: boolean;
+    /** Import `call` as the default export of `from`. Default: a named import. */
+    defaultImport?: boolean;
+    /** Insert before the step calling this function. Default: before the render. */
+    before?: string;
+    after?: string;
+    function?: string;
+}
+/**
+ * Adds a typed env key (decision 0020). `file` is the TypeScript file holding
+ * the schema: `env.ts` for `server`, `src/config/schema.ts` for `runtime`.
+ */
+export interface AddEnvKeyOp extends TransformBase {
+    op: 'add-env-key';
+    key: string;
+    scope: 'server' | 'runtime';
+    /**
+     * The schema as source text, for example `z.string().url()`. A map gives one per validator; the
+     * one matching the validator the schema file imports is used.
+     */
+    schema: string | Partial<Record<EnvValidator, string>>;
+    /** Placeholder written to `.env.example` (a list is joined with commas) or the runtime config files. Default: empty string. */
+    value?: Literal | string[];
+    /** The schema object's variable name for `runtime`. Defaults to `runtimeConfigSchema`. */
+    object?: string;
+    /** `server`: the dotenv example file to add a line to. Defaults to `.env.example`. */
+    example?: string;
+    /** `runtime`: the `runtime-config.<env>.json` files to add the key to. */
+    configFiles?: string[];
+}
+export interface AddRouteOp extends TransformBase {
+    op: 'add-route';
+    path: string;
+    component: string;
+    from: string;
+    /** Import `component` as the default export of `from`. Default: a named import. */
+    defaultImport?: boolean;
+    /** Name of the routes array. Defaults to `routes`. */
+    routes?: string;
+}
+export interface WorkflowStep {
+    name: string;
+    id?: string;
+    uses?: string;
+    run?: string;
+    with?: Record<string, Literal>;
+    env?: Record<string, string>;
+    if?: string;
+}
+export interface AddWorkflowStepOp extends TransformBase {
+    op: 'add-workflow-step';
+    job: string;
+    step: WorkflowStep;
+    /** Insert after the step with this name. Default: at the end. */
+    after?: string;
+}
+export type TransformOp = AddImportOp | WrapProviderOp | AddSharedOp | AddBootStepOp | AddEnvKeyOp | AddRouteOp | AddWorkflowStepOp;
+/** First-party only. Declared here so `upgrade` can read it; never run for third parties. */
+export interface FeatureMigration {
+    from: string;
+    to: string;
+    module: string;
+}
+/** `feature.json`: one installable feature, declarative. */
+export interface FeatureManifest {
+    $schema?: string;
+    name: string;
+    version: string;
+    description?: string;
+    prompts?: FeaturePrompt[];
+    requires?: string[];
+    conflicts?: string[];
+    files?: FeatureFile[];
+    dependencies?: FeatureDependency[];
+    scripts?: FeatureScript[];
+    transforms?: TransformOp[];
+    migrations?: FeatureMigration[];
+}
+/** Prefix of a `when` key that tests whether a feature is installed. */
+export declare const FEATURE_CONDITION = "feature:";
+export declare const FEATURE_NAME: RegExp;
+export declare const IDENT: RegExp;
+export declare const TARGET: RegExp;
+export declare const ENV_KEY: RegExp;
+export declare const JOB_ID: RegExp;
+export declare const SCRIPT_NAME: RegExp;
+export declare const PACKAGE: RegExp;
+/** A package in the project's own scope: `{{scope}}/contracts`. */
+export declare const SCOPED_PACKAGE: RegExp;
+/** What a first-party dependency name may be, for the JSON schema. */
+export declare const DEPENDENCY_NAME: RegExp;
+export declare function validateFeatureManifest(value: unknown): Issue[];
+export declare function isFeatureManifest(value: unknown): value is FeatureManifest;
+export {};

package/dist/html-injection.d.ts

@@ -0,0 +1,39 @@
+import type { RegistryIndex } from './registry.js';
+/** A remote module the current route renders, e.g. `{ remote: 'cart', expose: './MiniCart' }`. */
+export interface RouteNeed {
+    remote: string;
+    expose: string;
+}
+export interface InjectionOptions {
+    /**
+     * Whether the shell keeps Module Federation's manifest loader. Default false, like the
+     * production shell preset: a manifest-only remote then gets no hint, because the shell
+     * never fetches its manifest.
+     */
+    snapshot?: boolean;
+}
+/**
+ * The HTML an edge function or server adds to the shell's `index.html` for one
+ * route: the registry as `window.__MFE_REGISTRY__` (so the shell fetches no
+ * index) and preload hints for the files each remote the route renders needs.
+ * Everything the runtime reads from the fetched index is inlined, so both
+ * paths register the same remotes; only the per-expose `exposes` file lists
+ * stay out of the page.
+ *
+ * Hints match how the browser will request each file, or it downloads twice:
+ * classic scripts and styles are `rel="preload"` without `crossorigin`; the
+ * files of a `module`/`esm` remote are `rel="modulepreload"` (CORS anonymous
+ * by default, as `import()` fetches them); a remote with no `remoteEntry`
+ * (manifest only) gets its manifest as `preload as="fetch" crossorigin`,
+ * matching Module Federation's `fetch()`, but only when `snapshot` is set.
+ * Nothing here injects a `<script src>` for a remote entry: it needs the
+ * shell's runtime first. A remote the registry does not know gets no hints.
+ */
+export declare function registryInjection(index: RegistryIndex, needs: readonly RouteNeed[], options?: InjectionOptions): string;
+/**
+ * Adds `snippet` to the page's `<head>`: right after the `<meta charset>` when
+ * there is one (the browser only looks for the charset in the first 1024
+ * bytes, so nothing may push it back), else right after the opening tag.
+ * Throws if the page has no head.
+ */
+export declare function injectIntoHead(html: string, snippet: string): string;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { isSafeRelativePath, type Issue } from './validate.js';
+export { ANALYTICS_EVENT, EVENT_NAME, EXPOSE, isMfeManifest, MFE_NAME, ROUTE, validateMfeManifest, type MfeManifest, } from './mfe-manifest.js';
+export { assetsFromManifest, type RemoteAssets } from './manifest-assets.js';
+export { injectIntoHead, registryInjection, type InjectionOptions, type RouteNeed, } from './html-injection.js';
+export { isRegistryEntry, isRegistryIndex, validateRegistryEntry, validateRegistryIndex, type RegistryEntry, type RegistryIndex, type RegistryIndexRemote, } from './registry.js';
+export { FILE_HASH, isMfeflowProject, validateMfeflowProject, type MfeflowProject, type ProjectBudget, } from './project.js';
+export { COST_MODEL, judgeCost, round1, splitScripts, type CostLine, type CostModel, type CostSample, type CostVerdict, } from './cost-model.js';
+export { FEATURE_CONDITION, FEATURE_NAME, isFeatureManifest, TRANSFORM_OPS, validateFeatureManifest, type AddBootStepOp, type AddEnvKeyOp, type AddImportOp, type AddRouteOp, type AddSharedOp, type AddWorkflowStepOp, type EnvValidator, type FeatureCondition, type FeatureDependency, type FeatureFile, type FeatureManifest, type FeatureMigration, type FeaturePrompt, type FeatureScript, type FeatureTarget, type Literal, type PromptValue, type TransformOp, type TransformOpName, type WorkflowStep, type WrapProviderOp, } from './feature.js';
+export { DOCS_URL, SCHEMA_URLS, errorDocsUrl, type SchemaName } from './docs.js';
+export { JSON_SCHEMAS } from './json-schema.js';