@bleedingdev/modern-js-create 3.2.0-ultramodern.12 → 3.2.0-ultramodern.14

package/dist/index.js

@@ -1139,6 +1139,18 @@ import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
 
 const appId = '${app.id}';
 const port = Number(process.env['${app.portEnv}'] ?? ${app.port});
+const configuredSiteUrl = process.env['MODERN_PUBLIC_SITE_URL'];
+const hasConfiguredSiteUrl = typeof configuredSiteUrl === 'string' && configuredSiteUrl.length > 0;
+const isProductionBuild =
+  process.env['NODE_ENV'] === 'production' || process.argv.includes('build');
+
+if (isProductionBuild && !hasConfiguredSiteUrl) {
+  throw new Error(
+    'MODERN_PUBLIC_SITE_URL must be set for production builds so canonical and hreflang URLs use the deployed origin.',
+  );
+}
+
+const siteUrl = hasConfiguredSiteUrl ? configuredSiteUrl : \`http://localhost:\${port}\`;
 
 export default defineConfig(
   presetUltramodern(
@@ -1154,6 +1166,7 @@ export default defineConfig(
           localeDetection: {
             fallbackLanguage: 'en',
             languages: ['en', 'cs'],
+            localePathRedirect: true,
           },
         }),
         tanstackRouterPlugin(),
@@ -1166,6 +1179,11 @@ export default defineConfig(
           moduleFederationAppSSR: true,
         },
       },
+      source: {
+        globalVars: {
+          ULTRAMODERN_SITE_URL: siteUrl,
+        },
+      },
     },
     {
       appId,
@@ -1330,32 +1348,103 @@ export default defineRuntimeConfig({
 });
 `;
 }
+function createLocalizedHeadComponent(includeLocationSuffix = false) {
+    return `const fallbackLanguage = 'en';
+const supportedLanguages = ['en', 'cs'] as const;
+type SupportedLanguage = (typeof supportedLanguages)[number];
+
+const isSupportedLanguage = (value: string): value is SupportedLanguage =>
+  supportedLanguages.includes(value as SupportedLanguage);
+
+const stripLanguagePrefix = (pathname: string) => {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length > 0 && isSupportedLanguage(segments[0] ?? '')) {
+    segments.shift();
+  }
+  return \`/\${segments.join('/')}\`;
+};
+
+const localizedPath = (pathname: string, language: SupportedLanguage) => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname);
+  return pathWithoutLanguage === '/' ? \`/\${language}\` : \`/\${language}\${pathWithoutLanguage}\`;
+};
+
+const absoluteUrl = (pathname: string) => {
+  const origin = ULTRAMODERN_SITE_URL.replace(/\\/+$/u, '');
+  return \`\${origin}\${pathname}\`;
+};
+${includeLocationSuffix ? `
+const locationSuffix = (location: { hash?: unknown; search?: unknown; searchStr?: unknown }) => {
+  const { hash, search, searchStr } = location;
+  let locationSearch = '';
+  if (typeof searchStr === 'string') {
+    locationSearch = searchStr;
+  } else if (typeof search === 'string') {
+    locationSearch = search;
+  }
+  const locationHash = typeof hash === 'string' ? hash : '';
+  return \`\${locationSearch}\${locationHash}\`;
+};
+` : ''}
+const LocalizedHead = () => {
+  const { language } = useModernI18n();
+  const location = useLocation();
+  const currentLanguage = isSupportedLanguage(language) ? language : fallbackLanguage;
+  const canonicalPath = localizedPath(location.pathname, currentLanguage);
+
+  return (
+    <Helmet>
+      <link rel="canonical" href={absoluteUrl(canonicalPath)} />
+      {supportedLanguages.map((code) => (
+        <link
+          href={absoluteUrl(localizedPath(location.pathname, code))}
+          hrefLang={code}
+          key={code}
+          rel="alternate"
+        />
+      ))}
+      <link
+        href={absoluteUrl(localizedPath(location.pathname, fallbackLanguage))}
+        hrefLang="x-default"
+        rel="alternate"
+      />
+    </Helmet>
+  );
+};
+`;
+}
 function createShellPage() {
-    return `import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+    return `import { Helmet } from '@modern-js/runtime/head';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useLocation } from '@modern-js/plugin-tanstack/runtime';
 import { useTranslation } from 'react-i18next';
 
 const remotes = ['remote-commerce', 'remote-identity', 'remote-design-system'];
 
+${createLocalizedHeadComponent(true)}
 export default function ShellHome() {
   const { t } = useTranslation();
-  const { changeLanguage, language } = useModernI18n();
-  const languageOptions = [
-    { code: 'en', label: t('language.en') },
-    { code: 'cs', label: t('language.cs') },
-  ];
-
+  const { language } = useModernI18n();
+  const location = useLocation();
+  const currentLanguage = isSupportedLanguage(language) ? language : fallbackLanguage;
+  const suffix = locationSuffix(location);
+  const languageOptions = supportedLanguages.map((code) => ({
+    code,
+    href: \`\${localizedPath(location.pathname, code)}\${suffix}\`,
+    label: t(\`language.\${code}\`),
+  }));
   return (
     <main>
+      <LocalizedHead />
       <nav aria-label={t('language.switcher')}>
         {languageOptions.map((option) => (
-          <button
-            disabled={language === option.code}
+          <a
+            aria-current={currentLanguage === option.code ? 'page' : undefined}
+            href={option.href}
             key={option.code}
-            onClick={() => void changeLanguage(option.code)}
-            type="button"
           >
             {option.label}
-          </button>
+          </a>
         ))}
       </nav>
       <h1>{t('shell.title')}</h1>
@@ -1371,13 +1460,18 @@ export default function ShellHome() {
 `;
 }
 function createRemotePage(app) {
-    return `import { useTranslation } from 'react-i18next';
+    return `import { Helmet } from '@modern-js/runtime/head';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useLocation } from '@modern-js/plugin-tanstack/runtime';
+import { useTranslation } from 'react-i18next';
 
+${createLocalizedHeadComponent()}
 export default function ${toPascalCase(app.id)}Home() {
   const { t } = useTranslation();
 
   return (
     <main>
+      <LocalizedHead />
       <h1>{t('remote.title')}</h1>
       <p data-mf-role="${app.kind}">{t('remote.domain')}</p>
     </main>
@@ -1837,14 +1931,14 @@ function createTemplateManifest(modernVersion, packageSource) {
 function writeApp(targetDir, scope, app, packageSource) {
     writeJson(targetDir, `${app.directory}/package.json`, createAppPackage(scope, app, packageSource));
     writeJson(targetDir, `${app.directory}/tsconfig.json`, createPackageTsConfig(app.directory));
-    writeFile(targetDir, `${app.directory}/src/modern-app-env.d.ts`, "/// <reference types='@modern-js/app-tools/types' />\n");
+    writeFile(targetDir, `${app.directory}/src/modern-app-env.d.ts`, "/// <reference types='@modern-js/app-tools/types' />\n\ndeclare const ULTRAMODERN_SITE_URL: string;\n");
     writeFile(targetDir, `${app.directory}/modern.config.ts`, createAppModernConfig(app));
     writeFile(targetDir, `${app.directory}/src/modern.runtime.ts`, createAppRuntimeConfig());
     writeJson(targetDir, `${app.directory}/config/public/locales/en/translation.json`, createEnglishTranslations(app));
     writeJson(targetDir, `${app.directory}/config/public/locales/cs/translation.json`, createCzechTranslations(app));
     writeFile(targetDir, `${app.directory}/module-federation.config.ts`, 'shell' === app.kind ? createShellModuleFederationConfig() : createRemoteModuleFederationConfig(app));
     writeFile(targetDir, `${app.directory}/src/routes/layout.tsx`, createLayout(app.id));
-    writeFile(targetDir, `${app.directory}/src/routes/page.tsx`, 'shell' === app.kind ? createShellPage() : createRemotePage(app));
+    writeFile(targetDir, `${app.directory}/src/routes/[lang]/page.tsx`, 'shell' === app.kind ? createShellPage() : createRemotePage(app));
     if ('vertical' === app.kind) {
         writeFile(targetDir, `${app.directory}/src/remote-entry.tsx`, createRemoteEntry(app));
         const widgetFile = 'remote-identity' === app.id ? 'identity-widget.tsx' : 'commerce-widget.tsx';
@@ -1934,7 +2028,6 @@ const templateIdPattern = /^[a-z0-9][a-z0-9._-]*$/;
 const packageNamePattern = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/;
 const requiredDeniedPaths = [
     '.git/**',
-    '.github/**',
     '.npmrc',
     '.yarnrc',
     '.env',
@@ -2117,6 +2210,7 @@ function createBuiltinTemplateManifest(version) {
             allowedPaths: [
                 '.agents/**',
                 '.browserslistrc',
+                '.github/**',
                 '.gitignore',
                 '.modernjs/**',
                 '.nvmrc',
@@ -2129,10 +2223,12 @@ function createBuiltinTemplateManifest(version) {
                 'oxlint.config.ts',
                 'package.json',
                 'postcss.config.mjs',
+                'rstest.config.mts',
                 "scripts/**",
                 'shared/**',
                 'src/**',
                 'tailwind.config.ts',
+                'tests/**',
                 'tsconfig.json'
             ],
             deniedPaths: requiredDeniedPaths,
@@ -2161,10 +2257,13 @@ function createBuiltinTemplateManifest(version) {
             postMaterializationValidation: [
                 'ultramodern-contract-check',
                 'dependency-install-with-lifecycle-deny',
+                'package-source-retained',
+                'rstest-smoke-tests',
                 'template-manifest-retained'
             ],
             expectedCommands: [
                 "pnpm install --ignore-scripts",
+                'pnpm test',
                 'pnpm run ultramodern:check'
             ]
         }
@@ -2393,6 +2492,45 @@ function singleAppModernPackageSpecifier(packageName, packageSource, useWorkspac
     if ('install' !== packageSource.strategy || !packageSource.aliasScope) return packageSource.modernPackageVersion;
     return `npm:${src_modernAliasPackageName(packageName, packageSource)}@${packageSource.modernPackageVersion}`;
 }
+const singleAppModernPackages = [
+    '@modern-js/runtime',
+    '@modern-js/app-tools',
+    '@modern-js/tsconfig',
+    '@modern-js/plugin-i18n',
+    '@modern-js/plugin-tanstack',
+    '@modern-js/plugin-bff',
+    '@modern-js/adapter-rstest'
+];
+function createSingleAppPackageSourceEvidence(packageSource, useWorkspaceProtocol) {
+    const strategy = useWorkspaceProtocol ? 'workspace' : 'install';
+    const specifier = useWorkspaceProtocol ? 'workspace:*' : packageSource.modernPackageVersion;
+    const aliases = 'install' === strategy && packageSource.aliasScope ? Object.fromEntries(singleAppModernPackages.map((packageName)=>[
+            packageName,
+            src_modernAliasPackageName(packageName, packageSource)
+        ])) : void 0;
+    return {
+        schemaVersion: 1,
+        preset: 'presetUltramodern',
+        strategy,
+        modernPackages: {
+            specifier,
+            packages: singleAppModernPackages,
+            ...packageSource.registry ? {
+                registry: packageSource.registry
+            } : {},
+            ...aliases ? {
+                aliases
+            } : {}
+        }
+    };
+}
+function writeSingleAppPackageSourceEvidence(targetDir, packageSource, useWorkspaceProtocol) {
+    const evidencePath = node_path.join(targetDir, '.modernjs', 'ultramodern-package-source.json');
+    node_fs.mkdirSync(node_path.dirname(evidencePath), {
+        recursive: true
+    });
+    node_fs.writeFileSync(evidencePath, `${JSON.stringify(createSingleAppPackageSourceEvidence(packageSource, useWorkspaceProtocol), null, 2)}\n`);
+}
 function isDirectoryEmpty(dirPath) {
     if (!node_fs.existsSync(dirPath)) return false;
     try {
@@ -2515,6 +2653,7 @@ async function main() {
         version: useWorkspaceProtocol ? 'workspace:*' : packageSource.modernPackageVersion,
         runtimeVersion: singleAppModernPackageSpecifier('@modern-js/runtime', packageSource, useWorkspaceProtocol),
         appToolsVersion: singleAppModernPackageSpecifier('@modern-js/app-tools', packageSource, useWorkspaceProtocol),
+        adapterRstestVersion: singleAppModernPackageSpecifier('@modern-js/adapter-rstest', packageSource, useWorkspaceProtocol),
         tsconfigVersion: singleAppModernPackageSpecifier('@modern-js/tsconfig', packageSource, useWorkspaceProtocol),
         pluginTanstackVersion: singleAppModernPackageSpecifier('@modern-js/plugin-tanstack', packageSource, useWorkspaceProtocol),
         pluginBffVersion: singleAppModernPackageSpecifier('@modern-js/plugin-bff', packageSource, useWorkspaceProtocol),
@@ -2528,6 +2667,14 @@ async function main() {
     const targetPackageJson = node_path.join(targetDir, 'package.json');
     const packageJson = JSON.parse(node_fs.readFileSync(targetPackageJson, 'utf-8'));
     packageJson.name = generatedPackageName;
+    packageJson.modernjs = {
+        ...packageJson.modernjs ?? {},
+        preset: 'presetUltramodern',
+        packageSource: {
+            strategy: useWorkspaceProtocol ? 'workspace' : 'install',
+            config: './.modernjs/ultramodern-package-source.json'
+        }
+    };
     if (isSubproject) {
         delete packageJson['lint-staged'];
         delete packageJson['simple-git-hooks'];
@@ -2550,6 +2697,7 @@ async function main() {
     }
     node_fs.writeFileSync(targetPackageJson, `${JSON.stringify(packageJson, null, 2)}\n`);
     writeTemplateManifestEvidence(targetDir, templateManifest);
+    writeSingleAppPackageSourceEvidence(targetDir, packageSource, useWorkspaceProtocol);
     const dim = '\x1b[2m\x1b[3m';
     const reset = '\x1b[0m';
     console.log(`${i18n.t(localeKeys.message.success)}\n`);
@@ -2566,6 +2714,7 @@ function copyTemplate(src, dest, options) {
     });
     const excludeInSubproject = [
         '.agents',
+        '.github',
         '.gitignore.handlebars',
         'AGENTS.md',
         '.npmrc',
@@ -2595,6 +2744,7 @@ function copyTemplate(src, dest, options) {
                     version: options.version,
                     runtimeVersion: options.runtimeVersion,
                     appToolsVersion: options.appToolsVersion,
+                    adapterRstestVersion: options.adapterRstestVersion,
                     tsconfigVersion: options.tsconfigVersion,
                     pluginTanstackVersion: options.pluginTanstackVersion,
                     pluginBffVersion: options.pluginBffVersion,
@@ -2606,7 +2756,7 @@ function copyTemplate(src, dest, options) {
                     useHonoBff: 'hono' === options.bffRuntime,
                     bffRuntime: options.bffRuntime,
                     enableTailwind: options.enableTailwind,
-                    routerImportPath: 'tanstack' === options.routerFramework ? 'tanstack-router' : 'router'
+                    routerRuntimeImport: 'tanstack' === options.routerFramework ? '@modern-js/plugin-tanstack/runtime' : '@modern-js/runtime/router'
                 });
                 if (0 === rendered.trim().length) continue;
                 destPath = destPath.replace(/\.handlebars$/, '');

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.12",
+  "version": "3.2.0-ultramodern.14",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {
@@ -41,7 +41,7 @@
     "@types/node": "^25.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260516.1",
     "tsx": "^4.22.0",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.12"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.14"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -54,6 +54,6 @@
     "start": "node ./dist/index.js"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.12"
+    "frameworkVersion": "3.2.0-ultramodern.14"
   }
 }

package/template/.github/workflows/ultramodern-gates.yml.handlebars

@@ -21,7 +21,7 @@ jobs:
           cache: pnpm
 
       - name: Install Dependencies
-        run: pnpm install
+        run: pnpm install --ignore-scripts
 
       - name: Validate Ultramodern Contract
         run: pnpm run ultramodern:check

package/template/AGENTS.md

@@ -14,6 +14,8 @@ This project is generated for Codex-first UltraModern.js work.
 
 Runtime i18n is enabled by default. Agents must put user-visible UI copy in `config/public/locales/<lang>/translation.json` and render it through `react-i18next` or `@modern-js/plugin-i18n/runtime`. Do not add hardcoded JSX text, `aria-label`, `title`, `alt`, or `placeholder` strings unless the value is a non-translatable technical token.
 
+Routes are locale-prefixed by default through `localePathRedirect: true`. Keep localized pages under `src/routes/[lang]`, use links for language switching, and preserve canonical plus `hreflang` metadata. Production builds fail unless `MODERN_PUBLIC_SITE_URL` is set, so deployed canonical URLs always use the production origin.
+
 ## Private Skills
 
 Private orchestration skills are not vendored into this template. If you are authorized for `TechsioCZ/skills`, run:

package/template/modern.config.ts.handlebars

@@ -12,6 +12,18 @@ const enableTelemetryExporters =
   process.env['MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS'] !== 'false';
 const telemetryFailLoudStartup = process.env['MODERN_TELEMETRY_FAIL_LOUD_STARTUP'] !== 'false';
 const otlpEndpoint = process.env['MODERN_TELEMETRY_OTLP_ENDPOINT'];
+const configuredSiteUrl = process.env['MODERN_PUBLIC_SITE_URL'];
+const hasConfiguredSiteUrl = typeof configuredSiteUrl === 'string' && configuredSiteUrl.length > 0;
+const isProductionBuild =
+  process.env['NODE_ENV'] === 'production' || process.argv.includes('build');
+
+if (isProductionBuild && !hasConfiguredSiteUrl) {
+  throw new Error(
+    'MODERN_PUBLIC_SITE_URL must be set for production builds so canonical and hreflang URLs use the deployed origin.',
+  );
+}
+
+const siteUrl = hasConfiguredSiteUrl ? configuredSiteUrl : 'http://localhost:8080';
 const victoriaMetricsEndpoint = process.env['MODERN_TELEMETRY_VICTORIA_ENDPOINT'];
 
 // https://bleedingdev.github.io/ultramodern.js/configure/app/usage.html
@@ -32,6 +44,7 @@ export default defineConfig(
           localeDetection: {
             fallbackLanguage: 'en',
             languages: ['en', 'cs'],
+            localePathRedirect: true,
           },
         }),
 {{#if isTanstackRouter}}
@@ -39,6 +52,11 @@ export default defineConfig(
 {{/if}}{{#if enableBff}}
         bffPlugin(),
 {{/if}}      ],
+      source: {
+        globalVars: {
+          ULTRAMODERN_SITE_URL: siteUrl,
+        },
+      },
     },
     {
       appId,

package/template/package.json.handlebars

@@ -1,17 +1,22 @@
 {
   "name": "{{packageName}}",
   "version": "0.1.0",
+  "private": true,
   "type": "module",
+  "packageManager": "pnpm@11.1.2",
   "scripts": {
     "reset": "npx rimraf node_modules ./**/node_modules",
     "dev": "modern dev",
     "build": "modern build",
     "serve": "modern serve",
+    "test": "rstest run",
     "typecheck": "node -e \"const fs = require('node:fs'); const { execFileSync, spawnSync } = require('node:child_process'); const bin = execFileSync('effect-tsgo', ['get-exe-path'], { encoding: 'utf8' }).trim(); if (process.platform !== 'win32') fs.chmodSync(bin, 0o755); const result = spawnSync(bin, ['--noEmit', '-p', 'tsconfig.json'], { stdio: 'inherit' }); process.exit(result.status ?? 1);\"",
     "i18n:check": "node ./scripts/check-i18n-strings.mjs",
+{{#unless isSubproject}}
     "skills:install": "node ./scripts/bootstrap-agent-skills.mjs",
     "skills:check": "node ./scripts/bootstrap-agent-skills.mjs --check",
-    "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck && pnpm i18n:check{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
+{{/unless}}
+    "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck && pnpm i18n:check && pnpm test{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint .",
@@ -32,16 +37,20 @@
   },
   "devDependencies": {
     "@effect/tsgo": "0.7.3",
+    "@modern-js/adapter-rstest": "{{adapterRstestVersion}}",
     "@modern-js/app-tools": "{{appToolsVersion}}",
 {{#if enableBff}}    "@modern-js/plugin-bff": "{{pluginBffVersion}}",
 {{/if}}    "@modern-js/tsconfig": "{{tsconfigVersion}}",
+    "@rstest/core": "0.10.0",
 {{#if enableTailwind}}
     "@tailwindcss/postcss": "^4.1.18",
 {{/if}}
+    "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^20",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "happy-dom": "^20.8.9",
 {{#unless isSubproject}}
     "lint-staged": "~15.4.0",
     "oxfmt": "0.50.0",
@@ -62,6 +71,15 @@
     ]
   }{{/unless}},
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "pnpm": ">=11.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core",
+      "core-js",
+      "esbuild",
+      "msgpackr-extract"
+    ]
   }
 }

package/template/rstest.config.mts

@@ -0,0 +1,8 @@
+import { withModernConfig } from '@modern-js/adapter-rstest';
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  testEnvironment: 'happy-dom',
+  setupFiles: ['./tests/rstest.setup.ts'],
+});

package/template/scripts/validate-ultramodern.mjs.handlebars

@@ -3,6 +3,11 @@ import path from 'node:path';
 
 const configPath = path.resolve(process.cwd(), 'modern.config.ts');
 const templateManifestPath = path.resolve(process.cwd(), '.modernjs/mv-template-manifest.json');
+const packageSourcePath = path.resolve(
+  process.cwd(),
+  '.modernjs/ultramodern-package-source.json',
+);
+const isSubproject = {{isSubproject}};
 
 if (!fs.existsSync(configPath)) {
   console.error('modern.config.ts not found');
@@ -17,6 +22,10 @@ const requiredTokens = [
   'enableBffRequestId',
   'enableTelemetryExporters',
   'i18nPlugin(',
+  'localePathRedirect: true',
+  'ULTRAMODERN_SITE_URL',
+  'MODERN_PUBLIC_SITE_URL must be set for production builds',
+  'globalVars',
 ];
 const missing = requiredTokens.filter((token) => !content.includes(token));
 
@@ -33,7 +42,6 @@ if (!fs.existsSync(templateManifestPath)) {
 const templateManifest = JSON.parse(fs.readFileSync(templateManifestPath, 'utf-8'));
 const requiredDeniedPaths = [
   '.git/**',
-  '.github/**',
   '.npmrc',
   '.yarnrc',
   '.env',
@@ -44,17 +52,28 @@ const requiredDeniedPaths = [
 const requiredPostMaterialization = [
   'ultramodern-contract-check',
   'dependency-install-with-lifecycle-deny',
+  'package-source-retained',
+  'rstest-smoke-tests',
   'template-manifest-retained',
 ];
 const requiredPaths = [
+{{#unless isSubproject}}
   'AGENTS.md',
   '.agents/skills-lock.json',
+  '.github/workflows/ultramodern-gates.yml',
   'oxlint.config.ts',
   'oxfmt.config.ts',
   'scripts/bootstrap-agent-skills.mjs',
+{{/unless}}
+  '.modernjs/ultramodern-package-source.json',
+  'rstest.config.mts',
   'scripts/check-i18n-strings.mjs',
   'config/public/locales/en/translation.json',
   'config/public/locales/cs/translation.json',
+  'src/modern-app-env.d.ts',
+  'src/routes/[lang]/page.tsx',
+  'tests/rstest.setup.ts',
+  'tests/ultramodern.contract.test.ts',
 ];
 const manifestErrors = [];
 
@@ -65,6 +84,38 @@ for (const requiredPath of requiredPaths) {
   }
 }
 
+if (fs.existsSync(path.resolve(process.cwd(), 'src/routes/page.tsx'))) {
+  console.error('src/routes/page.tsx must move under src/routes/[lang]/page.tsx');
+  process.exit(1);
+}
+
+const pageContent = fs.readFileSync(
+  path.resolve(process.cwd(), 'src/routes/[lang]/page.tsx'),
+  'utf-8',
+);
+for (const token of [
+  'rel="canonical"',
+  'rel="alternate"',
+  'hrefLang="x-default"',
+  'localizedPath(',
+  '<a',
+{{#if isTanstackRouter}}
+  "@modern-js/plugin-tanstack/runtime",
+{{/if}}
+]) {
+  if (!pageContent.includes(token)) {
+    console.error(`Localized route is missing ${token}`);
+    process.exit(1);
+  }
+}
+{{#if isTanstackRouter}}
+const deprecatedTanstackRuntime = '@modern-js/runtime/' + 'tanstack-router';
+if (pageContent.includes(deprecatedTanstackRuntime)) {
+  console.error('Localized route must import TanStack runtime from @modern-js/plugin-tanstack/runtime');
+  process.exit(1);
+}
+{{/if}}
+
 if (templateManifest.schemaVersion !== 1) {
   manifestErrors.push('schemaVersion');
 }
@@ -111,22 +162,32 @@ if (manifestErrors.length > 0) {
 const packageJson = JSON.parse(
   fs.readFileSync(path.resolve(process.cwd(), 'package.json'), 'utf-8'),
 );
+const packageSource = JSON.parse(fs.readFileSync(packageSourcePath, 'utf-8'));
 const unresolvedTemplateMarker = String.fromCodePoint(123, 123);
 if (JSON.stringify(packageJson).includes(unresolvedTemplateMarker)) {
   console.error('package.json contains unresolved template markers');
   process.exit(1);
 }
+if (JSON.stringify(packageSource).includes(unresolvedTemplateMarker)) {
+  console.error('package source metadata contains unresolved template markers');
+  process.exit(1);
+}
+{{#unless isSubproject}}
 const skillsLock = JSON.parse(
   fs.readFileSync(path.resolve(process.cwd(), '.agents/skills-lock.json'), 'utf-8'),
 );
+{{/unless}}
 const requiredScripts = {
+  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
+  test: 'rstest run',
+{{#unless isSubproject}}
   format: 'oxfmt .',
   'format:check': 'oxfmt --check .',
-  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
   lint: 'oxlint .',
   'lint:fix': 'oxlint . --fix',
   'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
   'skills:install': 'node ./scripts/bootstrap-agent-skills.mjs',
+{{/unless}}
 };
 
 for (const [scriptName, scriptCommand] of Object.entries(requiredScripts)) {
@@ -144,6 +205,112 @@ if (
   process.exit(1);
 }
 
+if (!packageJson.scripts?.['ultramodern:check']?.includes('pnpm test')) {
+  console.error('ultramodern:check must run the generated Rstest suite');
+  process.exit(1);
+}
+
+if (packageJson.private !== true) {
+  console.error('Generated app package must be private by default');
+  process.exit(1);
+}
+
+if (packageJson.packageManager !== 'pnpm@11.1.2') {
+  console.error('Generated app package must pin pnpm@11.1.2');
+  process.exit(1);
+}
+
+if (packageJson.engines?.pnpm !== '>=11.0.0') {
+  console.error('Generated app package must require pnpm >=11.0.0');
+  process.exit(1);
+}
+
+if (packageJson.modernjs?.preset !== 'presetUltramodern') {
+  console.error('package.json must declare presetUltramodern metadata');
+  process.exit(1);
+}
+
+if (
+  packageJson.modernjs?.packageSource?.config !== './.modernjs/ultramodern-package-source.json'
+) {
+  console.error('package.json must retain package source metadata location');
+  process.exit(1);
+}
+
+if (packageSource.schemaVersion !== 1) {
+  console.error('Package source metadata must use schemaVersion 1');
+  process.exit(1);
+}
+
+if (packageSource.preset !== 'presetUltramodern') {
+  console.error('Package source metadata must declare presetUltramodern');
+  process.exit(1);
+}
+
+if (packageSource.strategy !== 'workspace' && packageSource.strategy !== 'install') {
+  console.error('Package source strategy must be workspace or install');
+  process.exit(1);
+}
+
+const expectedModernPackages = [
+  '@modern-js/runtime',
+  '@modern-js/app-tools',
+  '@modern-js/tsconfig',
+  '@modern-js/plugin-i18n',
+  '@modern-js/plugin-tanstack',
+  '@modern-js/plugin-bff',
+  '@modern-js/adapter-rstest',
+];
+
+for (const packageName of expectedModernPackages) {
+  if (!packageSource.modernPackages?.packages?.includes(packageName)) {
+    console.error(`Package source metadata must include ${packageName}`);
+    process.exit(1);
+  }
+}
+
+const expectedModernSpecifier = packageSource.modernPackages?.specifier;
+if (typeof expectedModernSpecifier !== 'string' || expectedModernSpecifier.length === 0) {
+  console.error('Package source metadata must provide a Modern package specifier');
+  process.exit(1);
+}
+
+const expectedModernDependency = (packageName) => {
+  const alias = packageSource.modernPackages?.aliases?.[packageName];
+  return typeof alias === 'string'
+    ? `npm:${alias}@${expectedModernSpecifier}`
+    : expectedModernSpecifier;
+};
+
+for (const packageName of [
+  '@modern-js/runtime',
+  '@modern-js/plugin-i18n',
+  '@modern-js/plugin-tanstack',
+]) {
+  if (
+    packageJson.dependencies?.[packageName] &&
+    packageJson.dependencies[packageName] !== expectedModernDependency(packageName)
+  ) {
+    console.error(`Dependency ${packageName} must match package source metadata`);
+    process.exit(1);
+  }
+}
+
+for (const packageName of [
+  '@modern-js/app-tools',
+  '@modern-js/adapter-rstest',
+  '@modern-js/tsconfig',
+  '@modern-js/plugin-bff',
+]) {
+  if (
+    packageJson.devDependencies?.[packageName] &&
+    packageJson.devDependencies[packageName] !== expectedModernDependency(packageName)
+  ) {
+    console.error(`Dev dependency ${packageName} must match package source metadata`);
+    process.exit(1);
+  }
+}
+
 for (const dependency of ['@modern-js/plugin-i18n', 'i18next', 'react-i18next']) {
   if (!packageJson.dependencies?.[dependency]) {
     console.error(`Missing dependency: ${dependency}`);
@@ -153,10 +320,16 @@ for (const dependency of ['@modern-js/plugin-i18n', 'i18next', 'react-i18next'])
 
 for (const dependency of [
   '@effect/tsgo',
+  '@modern-js/adapter-rstest',
+  '@rstest/core',
+  '@testing-library/jest-dom',
   '@typescript/native-preview',
+  'happy-dom',
+{{#unless isSubproject}}
   'oxlint',
   'oxfmt',
   'ultracite',
+{{/unless}}
 ]) {
   if (!packageJson.devDependencies?.[dependency]) {
     console.error(`Missing devDependency: ${dependency}`);
@@ -164,6 +337,7 @@ for (const dependency of [
   }
 }
 
+{{#unless isSubproject}}
 const privateSource = skillsLock.sources?.find(
   (source) => source.repository === 'https://github.com/TechsioCZ/skills',
 );
@@ -174,5 +348,6 @@ for (const skillName of ['plan-graph', 'dag', 'subagent-graph', 'helm', 'debugge
     process.exit(1);
   }
 }
+{{/unless}}
 
 console.log('Ultramodern contract check passed.');

package/template/src/modern-app-env.d.ts

@@ -1 +1,3 @@
 /// <reference types='@modern-js/app-tools/types' />
+
+declare const ULTRAMODERN_SITE_URL: string;

package/template/src/routes/{page.tsx.handlebars → [lang]/page.tsx.handlebars}

@@ -1,19 +1,62 @@
 import { Helmet } from '@modern-js/runtime/head';
 import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useLocation } from '{{routerRuntimeImport}}';
 {{#if useEffectBff}}import effectBff from '@api/effect/index';
 import { Effect } from '@modern-js/plugin-bff/effect-client';
 import { useEffect, useState } from 'react';
 {{/if}}
 import { useTranslation } from 'react-i18next';
-import './index.css';
+import '../index.css';
+
+const fallbackLanguage = 'en';
+const supportedLanguages = ['en', 'cs'] as const;
+type SupportedLanguage = (typeof supportedLanguages)[number];
+
+const isSupportedLanguage = (value: string): value is SupportedLanguage =>
+  supportedLanguages.includes(value as SupportedLanguage);
+
+const stripLanguagePrefix = (pathname: string) => {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length > 0 && isSupportedLanguage(segments[0] ?? '')) {
+    segments.shift();
+  }
+  return `/${segments.join('/')}`;
+};
+
+const localizedPath = (pathname: string, language: SupportedLanguage) => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname);
+  return pathWithoutLanguage === '/' ? `/${language}` : `/${language}${pathWithoutLanguage}`;
+};
+
+const absoluteUrl = (pathname: string) => {
+  const origin = ULTRAMODERN_SITE_URL.replace(/\/+$/u, '');
+  return `${origin}${pathname}`;
+};
+
+const locationSuffix = (location: { hash?: unknown; search?: unknown; searchStr?: unknown }) => {
+  const { hash, search, searchStr } = location;
+  let locationSearch = '';
+  if (typeof searchStr === 'string') {
+    locationSearch = searchStr;
+  } else if (typeof search === 'string') {
+    locationSearch = search;
+  }
+  const locationHash = typeof hash === 'string' ? hash : '';
+  return `${locationSearch}${locationHash}`;
+};
 
 const Index = () => {
   const { t } = useTranslation();
-  const { changeLanguage, language } = useModernI18n();
-  const languageOptions = [
-    { code: 'en', label: t('home.language.en') },
-    { code: 'cs', label: t('home.language.cs') },
-  ];
+  const { language } = useModernI18n();
+  const location = useLocation();
+  const currentLanguage = isSupportedLanguage(language) ? language : fallbackLanguage;
+  const canonicalPath = localizedPath(location.pathname, currentLanguage);
+  const suffix = locationSuffix(location);
+  const languageOptions = supportedLanguages.map((code) => ({
+    code,
+    href: `${localizedPath(location.pathname, code)}${suffix}`,
+    label: t(`home.language.${code}`),
+  }));
 {{#if useEffectBff}}  const [effectMessage, setEffectMessage] = useState('loading...');
 
   useEffect(() => {
@@ -42,18 +85,31 @@ const Index = () => {
           type="image/x-icon"
           href="https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico"
         />
+        <link rel="canonical" href={absoluteUrl(canonicalPath)} />
+        {supportedLanguages.map((code) => (
+          <link
+            href={absoluteUrl(localizedPath(location.pathname, code))}
+            hrefLang={code}
+            key={code}
+            rel="alternate"
+          />
+        ))}
+        <link
+          href={absoluteUrl(localizedPath(location.pathname, fallbackLanguage))}
+          hrefLang="x-default"
+          rel="alternate"
+        />
       </Helmet>
       <main>
         <nav className="language-switcher" aria-label={t('home.language.switcher')}>
           {languageOptions.map((option) => (
-            <button
-              disabled={language === option.code}
+            <a
+              aria-current={currentLanguage === option.code ? 'page' : undefined}
+              href={option.href}
               key={option.code}
-              onClick={() => void changeLanguage(option.code)}
-              type="button"
             >
               {option.label}
-            </button>
+            </a>
           ))}
         </nav>
         <div className="title">

package/template/src/routes/layout.tsx.handlebars

@@ -1,4 +1,4 @@
-import { Outlet } from '@modern-js/runtime/{{routerImportPath}}';
+import { Outlet } from '{{routerRuntimeImport}}';
 
 export default function Layout() {
   return (

package/template/tests/rstest.setup.ts

@@ -0,0 +1,4 @@
+import { expect } from '@rstest/core';
+import * as jestDomMatchers from '@testing-library/jest-dom/matchers';
+
+expect.extend(jestDomMatchers);

package/template/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["@testing-library/jest-dom", "@rstest/core/globals"]
+  },
+  "include": ["./"]
+}

package/template/tests/ultramodern.contract.test.ts

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, test } from '@rstest/core';
+
+const root = process.cwd();
+const readText = (relativePath: string) =>
+  fs.readFileSync(path.join(root, relativePath), 'utf-8');
+const readJson = <T>(relativePath: string): T =>
+  JSON.parse(readText(relativePath)) as T;
+
+describe('generated UltraModern contract', () => {
+  test('keeps localized route metadata and Rstest wiring', () => {
+    expect(fs.existsSync(path.join(root, 'src/routes/[lang]/page.tsx'))).toBe(
+      true,
+    );
+    expect(fs.existsSync(path.join(root, 'src/routes/page.tsx'))).toBe(false);
+
+    const page = readText('src/routes/[lang]/page.tsx');
+    expect(page).toContain('rel="canonical"');
+    expect(page).toContain('rel="alternate"');
+    expect(page).toContain('hrefLang="x-default"');
+    expect(page).toContain('localizedPath(');
+
+    const config = readText('rstest.config.mts');
+    expect(config).toContain("withModernConfig()");
+    expect(config).toContain("testEnvironment: 'happy-dom'");
+  });
+
+  test('retains package-source metadata for generated Modern.js packages', () => {
+    const packageJson = readJson<{
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      modernjs?: {
+        packageSource?: {
+          config?: string;
+        };
+        preset?: string;
+      };
+    }>('package.json');
+    const packageSource = readJson<{
+      modernPackages?: {
+        packages?: string[];
+        specifier?: string;
+      };
+      strategy?: string;
+    }>('.modernjs/ultramodern-package-source.json');
+
+    expect(packageJson.modernjs?.preset).toBe('presetUltramodern');
+    expect(packageJson.modernjs?.packageSource?.config).toBe(
+      './.modernjs/ultramodern-package-source.json',
+    );
+    expect(packageSource.strategy).toMatch(/^(workspace|install)$/u);
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/runtime',
+    );
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/app-tools',
+    );
+    expect(packageSource.modernPackages?.packages).toContain(
+      '@modern-js/adapter-rstest',
+    );
+    expect(packageSource.modernPackages?.specifier).toBeTruthy();
+    expect(
+      packageJson.devDependencies?.['@modern-js/adapter-rstest'],
+    ).toBeTruthy();
+  });
+});

package/template-workspace/AGENTS.md

@@ -14,6 +14,8 @@ This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents sh
 
 Runtime i18n is enabled by default for generated apps. Agents must put user-visible UI copy in each app's `config/public/locales/<lang>/translation.json` and render it through `react-i18next` or `@modern-js/plugin-i18n/runtime`. Do not add hardcoded JSX text, `aria-label`, `title`, `alt`, or `placeholder` strings unless the value is a non-translatable technical token.
 
+Routes are locale-prefixed by default through `localePathRedirect: true`. Keep localized app pages under `src/routes/[lang]`, use links for language switching, and preserve canonical plus `hreflang` metadata. Production builds fail unless `MODERN_PUBLIC_SITE_URL` is set per deployed app, so canonical URLs always use the production origin.
+
 ## Required Skill Baseline
 
 Use these skills when the task touches the matching subsystem:

package/template-workspace/scripts/validate-ultramodern-workspace.mjs.handlebars

@@ -65,25 +65,33 @@ const requiredPaths = [
   'apps/shell-super-app/config/public/locales/cs/translation.json',
   'apps/shell-super-app/modern.config.ts',
   'apps/shell-super-app/module-federation.config.ts',
+  'apps/shell-super-app/src/modern-app-env.d.ts',
   'apps/shell-super-app/src/modern.runtime.ts',
+  'apps/shell-super-app/src/routes/[lang]/page.tsx',
   'apps/remotes/remote-commerce/package.json',
   'apps/remotes/remote-commerce/config/public/locales/en/translation.json',
   'apps/remotes/remote-commerce/config/public/locales/cs/translation.json',
   'apps/remotes/remote-commerce/modern.config.ts',
   'apps/remotes/remote-commerce/module-federation.config.ts',
+  'apps/remotes/remote-commerce/src/modern-app-env.d.ts',
   'apps/remotes/remote-commerce/src/modern.runtime.ts',
+  'apps/remotes/remote-commerce/src/routes/[lang]/page.tsx',
   'apps/remotes/remote-identity/package.json',
   'apps/remotes/remote-identity/config/public/locales/en/translation.json',
   'apps/remotes/remote-identity/config/public/locales/cs/translation.json',
   'apps/remotes/remote-identity/modern.config.ts',
   'apps/remotes/remote-identity/module-federation.config.ts',
+  'apps/remotes/remote-identity/src/modern-app-env.d.ts',
   'apps/remotes/remote-identity/src/modern.runtime.ts',
+  'apps/remotes/remote-identity/src/routes/[lang]/page.tsx',
   'apps/remotes/remote-design-system/package.json',
   'apps/remotes/remote-design-system/config/public/locales/en/translation.json',
   'apps/remotes/remote-design-system/config/public/locales/cs/translation.json',
   'apps/remotes/remote-design-system/modern.config.ts',
   'apps/remotes/remote-design-system/module-federation.config.ts',
+  'apps/remotes/remote-design-system/src/modern-app-env.d.ts',
   'apps/remotes/remote-design-system/src/modern.runtime.ts',
+  'apps/remotes/remote-design-system/src/routes/[lang]/page.tsx',
   'services/service-recommendations-effect/package.json',
   'services/service-recommendations-effect/modern.config.ts',
   'services/service-recommendations-effect/api/effect/index.ts',
@@ -97,9 +105,23 @@ for (const requiredPath of requiredPaths) {
   assertExists(requiredPath);
 }
 
+for (const appDirectory of [
+  'apps/shell-super-app',
+  'apps/remotes/remote-commerce',
+  'apps/remotes/remote-identity',
+  'apps/remotes/remote-design-system',
+]) {
+  assert(
+    !fs.existsSync(path.join(root, appDirectory, 'src/routes/page.tsx')),
+    `${appDirectory} must use src/routes/[lang]/page.tsx`,
+  );
+}
+
 const rootPackage = readJson('package.json');
 const packageSource = readJson('.modernjs/ultramodern-package-source.json');
 const skillsLock = readJson('.agents/skills-lock.json');
+const pnpmWorkspace = readText('pnpm-workspace.yaml');
+const deprecatedTanstackRuntime = '@modern-js/runtime/' + 'tanstack-router';
 const expectedModernSpecifier =
   packageSource.strategy === 'install' ? packageSource.modernPackages?.specifier : 'workspace:*';
 
@@ -118,6 +140,16 @@ assert(rootPackage.private === true, 'Root package must be private');
 assert(rootPackage.modernjs?.preset === 'presetUltramodern', 'Root must declare presetUltramodern');
 assert(rootPackage.packageManager === 'pnpm@11.1.2', 'Root must pin pnpm 11.1.2');
 assert(rootPackage.engines?.pnpm === '>=11.0.0', 'Root must require pnpm >=11');
+for (const requiredSnippet of [
+  'packages:\n  - apps/*\n  - apps/remotes/*\n  - services/*\n  - packages/*',
+  "allowBuilds:\n  '@swc/core': true\n  core-js: true\n  esbuild: true\n  msgpackr-extract: true",
+  "onlyBuiltDependencies:\n  - '@swc/core'\n  - core-js\n  - esbuild\n  - msgpackr-extract",
+]) {
+  assert(
+    pnpmWorkspace.includes(requiredSnippet),
+    `pnpm-workspace.yaml must retain ${requiredSnippet.split('\n')[0]}`,
+  );
+}
 assert(
   rootPackage.modernjs?.packageSource?.config === './.modernjs/ultramodern-package-source.json',
   'Root must point to the UltraModern package source metadata',
@@ -286,6 +318,12 @@ for (const configPath of [
   const config = readText(configPath);
   assert(config.includes('presetUltramodern('), `${configPath} must use presetUltramodern`);
   assert(config.includes('i18nPlugin('), `${configPath} must enable plugin-i18n`);
+  assert(config.includes('localePathRedirect: true'), `${configPath} must prefix localized URLs`);
+  assert(config.includes('ULTRAMODERN_SITE_URL'), `${configPath} must expose site URL metadata`);
+  assert(
+    config.includes('MODERN_PUBLIC_SITE_URL must be set for production builds'),
+    `${configPath} must require MODERN_PUBLIC_SITE_URL for production builds`,
+  );
   assert(config.includes('tanstackRouterPlugin()'), `${configPath} must enable plugin-tanstack`);
   assert(
     config.includes('moduleFederationPlugin()'),
@@ -293,6 +331,27 @@ for (const configPath of [
   );
 }
 
+for (const routePath of [
+  'apps/shell-super-app/src/routes/[lang]/page.tsx',
+  'apps/remotes/remote-commerce/src/routes/[lang]/page.tsx',
+  'apps/remotes/remote-identity/src/routes/[lang]/page.tsx',
+  'apps/remotes/remote-design-system/src/routes/[lang]/page.tsx',
+]) {
+  const route = readText(routePath);
+  assert(route.includes('rel="canonical"'), `${routePath} must emit canonical metadata`);
+  assert(route.includes('rel="alternate"'), `${routePath} must emit alternate locale metadata`);
+  assert(route.includes('hrefLang="x-default"'), `${routePath} must emit x-default metadata`);
+  assert(route.includes('localizedPath('), `${routePath} must build localized URLs`);
+  assert(
+    route.includes('@modern-js/plugin-tanstack/runtime'),
+    `${routePath} must import TanStack runtime from @modern-js/plugin-tanstack/runtime`,
+  );
+  assert(
+    !route.includes(deprecatedTanstackRuntime),
+    `${routePath} must not import deprecated TanStack runtime path`,
+  );
+}
+
 const shellMf = readText('apps/shell-super-app/module-federation.config.ts');
 assert(shellMf.includes("name: 'shellSuperApp'"), 'Shell MF config must name the shell');
 assert(