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

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;

package/src/native-composition/rsc-disabled-plugin.ts

@@ -0,0 +1,117 @@
+import type { RsbuildPlugin, Rspack } from '@rsbuild/core';
+
+const disabledRuntimeModules = {
+  'react-server-dom-rspack/client.browser': './rscDisabledClientBrowserRuntime',
+  'react-server-dom-rspack/client.edge': './rscDisabledClientEdgeRuntime',
+  'react-server-dom-rspack/client.node': './rscDisabledClientNodeRuntime',
+  'react-server-dom-rspack/server.edge': './rscDisabledServerEdgeRuntime',
+  'react-server-dom-rspack/server.node': './rscDisabledServerNodeRuntime',
+} as const;
+
+const disabledRuntimeRequests = Object.keys(disabledRuntimeModules);
+
+function aliasMatchesRequest(aliasName: string, request: string) {
+  const exact = aliasName.endsWith('$');
+  const normalizedName = exact ? aliasName.slice(0, -1) : aliasName;
+  return exact
+    ? normalizedName === request
+    : request === normalizedName || request.startsWith(`${normalizedName}/`);
+}
+
+function objectAliasMatchesDisabledRuntime(aliasName: string) {
+  return disabledRuntimeRequests.some(request =>
+    aliasMatchesRequest(aliasName, request),
+  );
+}
+
+function arrayAliasMatchesDisabledRuntime(alias: {
+  name: string;
+  onlyModule?: boolean;
+}) {
+  const aliasName = `${alias.name}${alias.onlyModule ? '$' : ''}`;
+  return objectAliasMatchesDisabledRuntime(aliasName);
+}
+
+function normalizeArrayAliases(
+  aliases: Array<{
+    alias: string | false | Array<string | false>;
+    name: string;
+    onlyModule?: boolean;
+  }>,
+) {
+  const normalized: Record<string, string | false | Array<string | false>> = {};
+  for (const alias of aliases) {
+    if (arrayAliasMatchesDisabledRuntime(alias)) {
+      continue;
+    }
+    const aliasName = `${alias.name}${alias.onlyModule ? '$' : ''}`;
+    const existing = normalized[aliasName];
+    if (existing === undefined) {
+      normalized[aliasName] = alias.alias;
+      continue;
+    }
+    normalized[aliasName] = [
+      ...(Array.isArray(existing) ? existing : [existing]),
+      ...(Array.isArray(alias.alias) ? alias.alias : [alias.alias]),
+    ];
+  }
+  return normalized;
+}
+
+function resolveDisabledRuntimeModules() {
+  return Object.fromEntries(
+    Object.entries(disabledRuntimeModules).map(([request, moduleRequest]) => [
+      `${request}$`,
+      require.resolve(
+        `@modern-js/runtime-extensions/rsc-disabled/${moduleRequest.slice(2)}`,
+      ),
+    ]),
+  );
+}
+
+function applyDisabledRuntimeAliases(
+  config: Rspack.Configuration,
+  disabledAliases: Record<string, string>,
+) {
+  config.resolve ??= {};
+  if (Array.isArray(config.resolve.alias)) {
+    config.resolve.alias = {
+      ...disabledAliases,
+      ...normalizeArrayAliases(config.resolve.alias),
+    };
+  } else {
+    config.resolve.alias = {
+      ...disabledAliases,
+      ...Object.fromEntries(
+        Object.entries(config.resolve.alias ?? {}).filter(
+          ([aliasName]) => !objectAliasMatchesDisabledRuntime(aliasName),
+        ),
+      ),
+    };
+  }
+}
+
+export function rscDisabledRuntimePlugin(): RsbuildPlugin {
+  return {
+    name: 'builder:rsc-disabled-runtime',
+
+    setup(api) {
+      const disabledAliases = resolveDisabledRuntimeModules();
+
+      api.modifyRspackConfig({
+        order: 'post',
+        handler(config) {
+          applyDisabledRuntimeAliases(config, disabledAliases);
+        },
+      });
+      api.onBeforeCreateCompiler({
+        order: 'post',
+        handler({ bundlerConfigs }) {
+          for (const config of bundlerConfigs) {
+            applyDisabledRuntimeAliases(config, disabledAliases);
+          }
+        },
+      });
+    },
+  };
+}

package/src/native-composition/server-plugin.ts

@@ -0,0 +1 @@
+export { default } from '@modern-js/server-runtime-extensions/server-plugin';