@bleedingdev/modern-js-ultramodern-app-tools 0.0.0 → 3.9.0-ultramodern.5

package/dist/types-esm/native-composition/types.d.mts

@@ -0,0 +1,24 @@
+import type { AppUserConfig as NativeAppUserConfig } from '@modern-js/app-tools';
+import type { PrecompressConfig } from '@modern-js/app-tools-extensions/build-config/precompress/plugin';
+import type { CloudflareDeployConfig } from '@modern-js/app-tools-extensions/config';
+import type { BffRuntimeUserConfig, ServerTelemetryUserConfig } from '@modern-js/runtime-extensions/server-config';
+type NativeServerConfig = NonNullable<NativeAppUserConfig['server']>;
+type NativeSSRConfig = Exclude<NativeServerConfig['ssr'], boolean | undefined>;
+/** Native Modern.js configuration with the fork's explicitly owned options. */
+export type UltramodernAppUserConfig = Omit<NativeAppUserConfig, 'output' | 'server' | 'bff' | 'deploy'> & {
+    output?: Omit<NonNullable<NativeAppUserConfig['output']>, 'precompress'> & {
+        precompress?: boolean | PrecompressConfig;
+    };
+    server?: Omit<NativeServerConfig, 'ssr' | 'telemetry'> & {
+        ssr?: boolean | (NativeSSRConfig & {
+            moduleFederationAppSSR?: boolean;
+        });
+        telemetry?: ServerTelemetryUserConfig;
+    };
+    bff?: Omit<NonNullable<NativeAppUserConfig['bff']>, keyof BffRuntimeUserConfig> & BffRuntimeUserConfig & {
+        requestId?: string;
+    };
+    deploy?: NonNullable<NativeAppUserConfig['deploy']> & CloudflareDeployConfig;
+};
+export type AppUserConfig = UltramodernAppUserConfig;
+export {};

package/package.json

@@ -1,16 +1,111 @@
 {
   "name": "@bleedingdev/modern-js-ultramodern-app-tools",
-  "version": "0.0.0",
-  "description": "Package-name registration for the forthcoming UltraModern.js release. This setup version contains no runtime implementation.",
-  "license": "MIT",
+  "description": "Native UltraModern.js build, preset and release plugin composition.",
+  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "bugs": {
+    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git"
+    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "directory": "packages/solutions/ultramodern-app-tools"
   },
+  "license": "MIT",
+  "version": "3.9.0-ultramodern.5",
   "files": [
-    "README.md"
+    "dist",
+    "src"
   ],
+  "types": "./dist/types/native-composition/index.d.ts",
+  "main": "./dist/cjs/native-composition/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types-esm/native-composition/index.d.mts",
+        "default": "./dist/esm-node/native-composition/index.mjs"
+      },
+      "require": {
+        "types": "./dist/types/native-composition/index.d.ts",
+        "default": "./dist/cjs/native-composition/index.js"
+      },
+      "types": "./dist/types/native-composition/index.d.ts"
+    },
+    "./server-plugin": {
+      "node": {
+        "import": {
+          "types": "./dist/types-esm/native-composition/server-plugin.d.mts",
+          "default": "./dist/esm-node/native-composition/server-plugin.mjs"
+        },
+        "require": {
+          "types": "./dist/types/native-composition/server-plugin.d.ts",
+          "default": "./dist/cjs/native-composition/server-plugin.js"
+        }
+      },
+      "types": "./dist/types/native-composition/server-plugin.d.ts"
+    },
+    "./router-runtime": {
+      "node": {
+        "import": {
+          "types": "./dist/types-esm/native-composition/router-runtime.d.mts",
+          "default": "./dist/esm-node/native-composition/router-runtime.mjs"
+        },
+        "require": {
+          "types": "./dist/types/native-composition/router-runtime.d.ts",
+          "default": "./dist/cjs/native-composition/router-runtime.js"
+        }
+      },
+      "default": "./dist/esm/native-composition/router-runtime.mjs",
+      "types": "./dist/types-esm/native-composition/router-runtime.d.mts"
+    }
+  },
+  "engines": {
+    "node": ">=26.7.0"
+  },
+  "dependencies": {
+    "@modern-js/app-tools": "npm:@bleedingdev/modern-js-app-tools@3.9.0-ultramodern.5",
+    "@modern-js/app-tools-extensions": "npm:@bleedingdev/modern-js-app-tools-extensions@3.9.0-ultramodern.5",
+    "@modern-js/i18n-integration": "npm:@bleedingdev/modern-js-i18n-integration@3.9.0-ultramodern.5",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.9.0-ultramodern.5",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.5",
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.9.0-ultramodern.5",
+    "@modern-js/runtime-renderer-extensions": "npm:@bleedingdev/modern-js-runtime-renderer-extensions@3.9.0-ultramodern.5",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.9.0-ultramodern.5",
+    "@modern-js/server-runtime-extensions": "npm:@bleedingdev/modern-js-server-runtime-extensions@3.9.0-ultramodern.5",
+    "@rsbuild/core": "2.2.3"
+  },
+  "devDependencies": {
+    "@modern-js/backend-federation-contracts": "npm:@bleedingdev/modern-js-backend-federation-contracts@3.9.0-ultramodern.5",
+    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.9.0-ultramodern.5",
+    "@modern-js/plugin-bff": "npm:@bleedingdev/modern-js-plugin-bff@3.9.0-ultramodern.5",
+    "@modern-js/plugin-tanstack": "npm:@bleedingdev/modern-js-plugin-tanstack@3.9.0-ultramodern.5",
+    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.9.0-ultramodern.5",
+    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.9.0-ultramodern.5",
+    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.0-ultramodern.5",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.5",
+    "@rslib/core": "1.0.0",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.4.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "typesVersions": {
+    "*": {
+      "server-plugin": [
+        "./dist/types/native-composition/server-plugin.d.ts",
+        "./src/native-composition/server-plugin.ts"
+      ],
+      "router-runtime": [
+        "./dist/types/native-composition/router-runtime.d.ts",
+        "./src/native-composition/router-runtime.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "rslib build && pnpm run verify:deploy-output",
+    "test": "rstest",
+    "verify:deploy-output": "node ./tests/deploy-output/verify-public-surface.mjs"
   }
 }

package/src/native-composition/index.ts

@@ -0,0 +1,59 @@
+import { type AppTools, appTools, type CliPlugin } from '@modern-js/app-tools';
+import backendFederationBuildPlugin from '@modern-js/app-tools-extensions/backend-federation-build';
+import { createCloudflareBuilderPlugin } from '@modern-js/app-tools-extensions/cloudflare-builder';
+import { createDeployOutputAliasesPlugin } from '@modern-js/app-tools-extensions/deploy-output/plugin';
+import { ultramodernI18nIntegrationPlugin } from '@modern-js/i18n-integration';
+import { ultramodernReleaseEnvelopePlugin } from './release-envelope-plugin';
+import { ultramodernRouterIntegrationPlugin } from './router-integration-plugin';
+import { rscDisabledRuntimePlugin } from './rsc-disabled-plugin';
+import { ultramodernSSRIntegrationPlugin } from './ssr-integration-plugin';
+
+export {
+  createPresetUltramodernConfig,
+  type PresetUltramodernOptions,
+  presetUltramodern,
+} from './preset';
+export { ultramodernReleaseEnvelopePlugin } from './release-envelope-plugin';
+export type { AppUserConfig, UltramodernAppUserConfig } from './types';
+
+/** Compose the fork's build and release features through native CLI plugins. */
+export const ultramodernAppTools = (): CliPlugin<AppTools> => ({
+  name: '@modern-js/ultramodern-app-tools',
+  usePlugins: [
+    appTools(),
+    ultramodernI18nIntegrationPlugin(),
+    ultramodernRouterIntegrationPlugin(),
+    ultramodernSSRIntegrationPlugin(),
+    backendFederationBuildPlugin(),
+    createCloudflareBuilderPlugin(),
+    createDeployOutputAliasesPlugin(),
+    ultramodernReleaseEnvelopePlugin(),
+  ],
+  setup(api) {
+    api.modifyResolvedConfig(config => {
+      if (config.server?.rsc) return config;
+      return {
+        ...config,
+        builderPlugins: [
+          ...(config.builderPlugins ?? []),
+          rscDisabledRuntimePlugin(),
+        ],
+      };
+    });
+    api._internalServerPlugins(({ plugins }) => {
+      const name = '@modern-js/ultramodern-app-tools/server-plugin';
+      if (!plugins.some(plugin => plugin.name === name)) {
+        plugins.push({ name });
+      }
+      return { plugins };
+    });
+    api._internalRuntimePlugins(({ entrypoint, plugins }) => {
+      plugins.push({
+        name: 'rendererHead',
+        path: '@modern-js/runtime-renderer-extensions',
+        config: {},
+      });
+      return { entrypoint, plugins };
+    });
+  },
+});

package/src/native-composition/preset.ts

@@ -0,0 +1,338 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { builderPluginAdapterPrecompress } from '@modern-js/app-tools-extensions/build-config/precompress/plugin';
+import { resolveEffectTsgoCompiler } from '@modern-js/app-tools-extensions/config';
+import { configureUltramodernTypeChecker } from '@modern-js/app-tools-extensions/native-type-checker';
+import { resolveUltramodernReleaseIdentity } from '@modern-js/app-tools-extensions/release-identity';
+import { mergeConfig } from '@modern-js/plugin/cli';
+import { type RspackChain, rspack } from '@rsbuild/core';
+import type { AppUserConfig } from './types';
+
+const DEFAULT_OTLP_ENDPOINT = 'http://127.0.0.1:4318/v1/logs';
+const DEFAULT_VICTORIA_METRICS_ENDPOINT =
+  'http://127.0.0.1:8428/api/v1/import/prometheus';
+
+export interface PresetUltramodernOptions {
+  /**
+   * Stable producer identity used by BFF cross-project clients.
+   * @default "app"
+   */
+  appId?: string;
+  /**
+   * Generation-time identity root for a generated delivery unit. When set, the
+   * preset derives one build identity from the immutable source revision and
+   * injects it into every browser, SSR, API, and backend bundle.
+   */
+  deliveryUnit?: {
+    buildMarker: string;
+    unitId: string;
+    version: string;
+  };
+  /**
+   * Enable BFF requestId contract by default.
+   * @default true
+   */
+  enableBffRequestId?: boolean;
+  /**
+   * Enable telemetry contract by default.
+   * Exporters are still configured separately by applications.
+   * @default true
+   */
+  enableTelemetry?: boolean;
+  /**
+   * Enable telemetry exporters.
+   *
+   * By default each exporter is enabled only when its endpoint is explicitly
+   * configured (via the matching option or environment variable), so a bare
+   * preset app boots in production without local collectors.
+   * Set `true` to force both exporters on with their default localhost
+   * endpoints, or `false` to disable exporters entirely.
+   * @default undefined (endpoint-driven)
+   */
+  enableTelemetryExporters?: boolean;
+  /**
+   * OTLP exporter endpoint. Setting it (or the environment variable)
+   * enables the OTLP exporter unless `enableTelemetryExporters` is `false`.
+   * The localhost endpoint is used only when exporters are forced on with
+   * `enableTelemetryExporters: true` and no endpoint was provided.
+   * @default process.env.MODERN_TELEMETRY_OTLP_ENDPOINT
+   */
+  otlpEndpoint?: string;
+  /**
+   * VictoriaMetrics exporter endpoint. Setting it (or the environment
+   * variable) enables the VictoriaMetrics exporter unless
+   * `enableTelemetryExporters` is `false`.
+   * The localhost endpoint is used only when exporters are forced on with
+   * `enableTelemetryExporters: true` and no endpoint was provided.
+   * @default process.env.MODERN_TELEMETRY_VICTORIA_ENDPOINT
+   */
+  victoriaMetricsEndpoint?: string;
+  /**
+   * Enable fail-loud startup probing for telemetry exporters.
+   * Probes only run for exporters that are actually enabled.
+   * @default false
+   */
+  telemetryFailLoudStartup?: boolean;
+  /**
+   * Enable app-level Module Federation SSR handshake by default.
+   * @default true
+   */
+  enableModuleFederationSSR?: boolean;
+}
+
+const resolveReactRouterPackageDir = (appDirectory: string) => {
+  const resolveNodeModulePackageJson = (
+    packageName: string,
+    fromDirectory: string,
+  ) => {
+    let currentDirectory = path.resolve(fromDirectory);
+
+    while (true) {
+      const packageJson = path.join(
+        currentDirectory,
+        'node_modules',
+        packageName,
+        'package.json',
+      );
+      if (fs.existsSync(packageJson)) {
+        return fs.realpathSync(packageJson);
+      }
+
+      const parentDirectory = path.dirname(currentDirectory);
+      if (parentDirectory === currentDirectory) {
+        return undefined;
+      }
+      currentDirectory = parentDirectory;
+    }
+  };
+
+  const reactRouterPackageJson = resolveNodeModulePackageJson(
+    'react-router',
+    appDirectory,
+  );
+  if (reactRouterPackageJson) {
+    return path.dirname(reactRouterPackageJson);
+  }
+
+  const reactRouterDomPackageJson = resolveNodeModulePackageJson(
+    'react-router-dom',
+    appDirectory,
+  );
+  if (!reactRouterDomPackageJson) {
+    return undefined;
+  }
+
+  const nestedReactRouterPackageJson = resolveNodeModulePackageJson(
+    'react-router',
+    path.dirname(reactRouterDomPackageJson),
+  );
+  if (nestedReactRouterPackageJson) {
+    return path.dirname(nestedReactRouterPackageJson);
+  }
+
+  return undefined;
+};
+
+// Dependency-driven opt-in surface for apps that explicitly install
+// react-router/react-router-dom. Default TanStack workspaces install neither,
+// so resolveReactRouterPackageDir returns undefined and this must no-op.
+// Do not remove as dead code: it is the supported escape hatch for apps that
+// bring their own react-router dependency.
+const setReactRouterBridgeSafeAliases = (
+  chain: RspackChain,
+  { isProd }: { isProd: boolean },
+) => {
+  const chainContext = chain.get('context');
+  const appDirectory =
+    typeof chainContext === 'string' && chainContext.length > 0
+      ? chainContext
+      : process.cwd();
+  const reactRouterPackageDir = resolveReactRouterPackageDir(appDirectory);
+  if (!reactRouterPackageDir) {
+    return;
+  }
+
+  const productionEntry = path.join(
+    reactRouterPackageDir,
+    'dist/production/index.mjs',
+  );
+  const developmentEntry = path.join(
+    reactRouterPackageDir,
+    'dist/development/index.mjs',
+  );
+
+  chain.resolve.alias.set(
+    'react-router$',
+    isProd ? productionEntry : developmentEntry,
+  );
+  chain.resolve.alias.set(
+    'react-router/dist/production/index.js',
+    productionEntry,
+  );
+  chain.resolve.alias.set(
+    'react-router/dist/development/index.js',
+    developmentEntry,
+  );
+};
+
+/**
+ * Materialize a fresh UltraModern preset config.
+ *
+ * This is the advanced inspection API. Use `presetUltramodern` when composing
+ * an application config so nested records, arrays, and hooks keep the normal
+ * Modern.js merge behavior.
+ */
+export const createPresetUltramodernConfig = (
+  options: PresetUltramodernOptions = {},
+): AppUserConfig => {
+  const {
+    appId = 'app',
+    deliveryUnit,
+    enableBffRequestId = true,
+    enableTelemetry = true,
+    enableTelemetryExporters,
+    otlpEndpoint = process.env.MODERN_TELEMETRY_OTLP_ENDPOINT,
+    victoriaMetricsEndpoint = process.env.MODERN_TELEMETRY_VICTORIA_ENDPOINT,
+    telemetryFailLoudStartup = false,
+    enableModuleFederationSSR = true,
+  } = options;
+
+  const server: NonNullable<AppUserConfig['server']> = {};
+  const releaseIdentity = deliveryUnit
+    ? resolveUltramodernReleaseIdentity({
+        generationBuildMarker: deliveryUnit.buildMarker,
+        unitId: deliveryUnit.unitId,
+      })
+    : undefined;
+  const bundledReleaseIdentity = releaseIdentity
+    ? {
+        ...releaseIdentity,
+        releaseVersion: deliveryUnit!.version,
+      }
+    : undefined;
+
+  if (enableTelemetry) {
+    server.telemetry = {
+      enabled: true,
+      failLoudStartup: telemetryFailLoudStartup,
+    };
+
+    if (enableTelemetryExporters !== false) {
+      const exporters: NonNullable<
+        NonNullable<typeof server.telemetry>['exporters']
+      > = {};
+
+      if (enableTelemetryExporters === true || otlpEndpoint) {
+        exporters.otlp = {
+          enabled: true,
+          endpoint: otlpEndpoint || DEFAULT_OTLP_ENDPOINT,
+        };
+      }
+
+      if (enableTelemetryExporters === true || victoriaMetricsEndpoint) {
+        exporters.victoriaMetrics = {
+          enabled: true,
+          endpoint:
+            victoriaMetricsEndpoint || DEFAULT_VICTORIA_METRICS_ENDPOINT,
+        };
+      }
+
+      if (Object.keys(exporters).length > 0) {
+        server.telemetry.exporters = exporters;
+      }
+    }
+  }
+
+  if (enableModuleFederationSSR) {
+    server.ssr = {
+      mode: 'stream',
+      moduleFederationAppSSR: true,
+    };
+  }
+
+  const presetConfig: AppUserConfig = {
+    output: {
+      // Keep build artifacts predictable across apps.
+      precompress: true,
+    },
+    server,
+    source: {
+      reactCompiler: true,
+      ...(deliveryUnit
+        ? {
+            globalVars: {
+              ULTRAMODERN_BUILD_MARKER: releaseIdentity?.buildMarker,
+              ULTRAMODERN_RELEASE_VERSION: deliveryUnit.version,
+              ULTRAMODERN_SOURCE_REVISION: releaseIdentity?.sourceRevision,
+            },
+          }
+        : {}),
+    },
+    tools: {
+      bundlerChain: (chain, utils) => {
+        setReactRouterBridgeSafeAliases(chain, utils);
+        configureUltramodernTypeChecker(
+          chain,
+          utils.CHAIN_ID.PLUGIN.TS_CHECKER,
+          from => resolveEffectTsgoCompiler({ from }),
+        );
+      },
+      // Keep generated Tailwind apps on Rsbuild's native CSS pipeline.
+      lightningcssLoader: true,
+      ...(bundledReleaseIdentity
+        ? {
+            rspack: config => {
+              config.plugins ??= [];
+              config.plugins.push(
+                new rspack.BannerPlugin({
+                  banner: `void ${JSON.stringify(bundledReleaseIdentity.buildMarker)};void ${JSON.stringify(bundledReleaseIdentity.sourceRevision)};void ${JSON.stringify(bundledReleaseIdentity.releaseVersion)};`,
+                  raw: true,
+                  // The default additions stage runs before production
+                  // minimization, which removes side-effect-free identity
+                  // expressions from browser and Module Federation assets.
+                  // Inject after minimization but before Rspack derives asset
+                  // hashes, so the identity survives in browser assets and a
+                  // changed identity necessarily changes [contenthash].
+                  stage: rspack.Compilation.PROCESS_ASSETS_STAGE_SUMMARIZE,
+                  test: /\.(?:c|m)?js$/u,
+                }),
+              );
+              return config;
+            },
+          }
+        : {}),
+    },
+  };
+
+  if (enableBffRequestId) {
+    presetConfig.bff = {
+      requestId: appId,
+    };
+  }
+
+  return presetConfig;
+};
+
+/**
+ * Compose an application config over the UltraModern preset.
+ *
+ * The application config is merged after the preset. Nested records are
+ * preserved, scalar values and `false` override preset values, and omitted or
+ * `undefined` values keep the preset value. Arrays and hooks compose in
+ * preset-first order. An empty record does not reset nested preset defaults;
+ * use the typed `PresetUltramodernOptions` opt-outs instead.
+ */
+export const presetUltramodern = (
+  config: AppUserConfig,
+  options: PresetUltramodernOptions = {},
+): AppUserConfig => {
+  const merged = mergeConfig<AppUserConfig, AppUserConfig>([
+    createPresetUltramodernConfig(options),
+    config,
+  ]);
+  merged.builderPlugins = [
+    builderPluginAdapterPrecompress(merged.output?.precompress),
+    ...(merged.builderPlugins ?? []),
+  ];
+  return merged;
+};

package/src/native-composition/release-envelope-plugin.ts

@@ -0,0 +1,6 @@
+import type { AppTools, CliPlugin } from '@modern-js/app-tools';
+import { resolveDeployTarget } from '@modern-js/app-tools-extensions/deploy-output/target';
+import { createUltramodernReleaseEnvelopePlugin } from '@modern-js/app-tools-extensions/release-envelope/plugin';
+
+export const ultramodernReleaseEnvelopePlugin = (): CliPlugin<AppTools> =>
+  createUltramodernReleaseEnvelopePlugin({ resolveDeployTarget });

package/src/native-composition/router-integration-plugin.ts

@@ -0,0 +1,20 @@
+import type { AppTools, CliPlugin } from '@modern-js/app-tools';
+
+/** Add fork router policy after the native and optional provider selectors. */
+export const ultramodernRouterIntegrationPlugin = (): CliPlugin<AppTools> => ({
+  name: '@modern-js/ultramodern-router-integration',
+  pre: ['@modern-js/plugin-router', '@modern-js/plugin-tanstack'],
+  setup(api) {
+    api._internalRuntimePlugins(({ entrypoint, plugins }) => ({
+      entrypoint,
+      plugins: plugins.map(plugin =>
+        plugin.path === '@modern-js/runtime/router/internal'
+          ? {
+              ...plugin,
+              path: '@modern-js/ultramodern-app-tools/router-runtime',
+            }
+          : plugin,
+      ),
+    }));
+  },
+});

package/src/native-composition/router-runtime.ts

@@ -0,0 +1,28 @@
+import {
+  routerPlugin as nativeRouterPlugin,
+  routerProviderRegistryHooks,
+} from '@modern-js/runtime/router/internal';
+import { createRouterPlugin } from '@modern-js/runtime-extensions/router-provider';
+import { createRouterStatePlugin } from '@modern-js/runtime-extensions/router-state-plugin';
+
+const createProvider = createRouterPlugin({
+  defaultProvider: { name: 'react-router', factory: nativeRouterPlugin },
+  registryHooks: routerProviderRegistryHooks,
+});
+
+/** Install fork observers before the native provider registers its lifecycle. */
+export const routerPlugin: typeof nativeRouterPlugin = config => {
+  const state = createRouterStatePlugin({
+    registryHooks: routerProviderRegistryHooks,
+  });
+  const provider = createProvider(config);
+  return {
+    ...provider,
+    setup(api) {
+      state.setup?.(api);
+      return provider.setup?.(api);
+    },
+  };
+};
+
+export default routerPlugin;