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

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/runtime/tanstack-router';
 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/runtime/tanstack-router';
+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';

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.12",
+  "version": "3.2.0-ultramodern.13",
   "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.13"
   },
   "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.13"
   }
 }

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/scripts/validate-ultramodern.mjs.handlebars

@@ -17,6 +17,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));
 
@@ -55,6 +59,8 @@ const requiredPaths = [
   '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',
 ];
 const manifestErrors = [];
 
@@ -65,6 +71,28 @@ 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 (!pageContent.includes(token)) {
+    console.error(`Localized route is missing ${token}`);
+    process.exit(1);
+  }
+}
+
 if (templateManifest.schemaVersion !== 1) {
   manifestErrors.push('schemaVersion');
 }

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 '@modern-js/runtime/{{routerImportPath}}';
 {{#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-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,6 +105,18 @@ 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');
@@ -286,6 +306,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 +319,19 @@ 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`);
+}
+
 const shellMf = readText('apps/shell-super-app/module-federation.config.ts');
 assert(shellMf.includes("name: 'shellSuperApp'"), 'Shell MF config must name the shell');
 assert(