@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/LLM/frontend/REMIX-15.3-upgrade-llm.md

@@ -0,0 +1,1245 @@
+# Remix 2.15.3 Upgrade Summary - Frontend Server
+
+## Upgrade Completed: November 2025
+
+This document summarizes the changes made to upgrade the `yantra-stack/servers/frontend-server` to **Remix 2.15.3** with v3 future flags.
+
+## Dependency Version Updates
+
+As part of this upgrade, the following major dependencies were also updated:
+
+### @common-stack packages (updated to 8.2.2-alpha.0)
+
+| Package                              | Old Version    | New Version       |
+| ------------------------------------ | -------------- | ----------------- |
+| `@common-stack/env-list-loader`      | 7.2.1-alpha.5  | **8.2.2-alpha.0** |
+| `@common-stack/generate-plugin`      | 7.2.1-alpha.12 | **8.2.2-alpha.0** |
+| `@common-stack/rollup-vite-utils`    | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/cache-api-server`     | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/client-core`          | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/client-react`         | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/components-pro`       | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/core`                 | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/frontend-stack-react` | 7.2.1-alpha.12 | **8.2.2-alpha.0** |
+| `@common-stack/remix-router-redux`   | 7.2.1-alpha.5  | **8.2.2-alpha.0** |
+| `@common-stack/server-core`          | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+| `@common-stack/server-stack`         | 7.2.1-alpha.12 | **8.2.2-alpha.0** |
+| `@common-stack/store-mongo`          | 7.2.1-alpha.11 | **8.2.2-alpha.0** |
+
+### @adminide-stack packages (updated to 13.0.4-alpha.x)
+
+| Package                                      | Old Version      | New Version        |
+| -------------------------------------------- | ---------------- | ------------------ |
+| `@adminide-stack/account-api-server`         | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/extension-module-server`    | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/marketplace-module-server`  | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/platform-server`            | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/project-mgmt-server`        | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/user-auth0-server`          | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/account-api-browser`        | 12.0.4-alpha.351 | **13.0.4-alpha.1** |
+| `@adminide-stack/account-api-client`         | 12.0.4-alpha.349 | **13.0.4-alpha.1** |
+| `@adminide-stack/extension-module-browser`   | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/marketplace-module-browser` | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/mongo-admin-browser`        | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/platform-browser`           | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/platform-client`            | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/project-mgmt-browser`       | 12.0.4-alpha.351 | **13.0.4-alpha.1** |
+| `@adminide-stack/react-shared-components`    | 12.0.4-alpha.348 | **13.0.4-alpha.0** |
+| `@adminide-stack/user-auth0-browser`         | 12.0.4-alpha.349 | **13.0.4-alpha.1** |
+
+### @admin-layout packages (updated to 12.2.1-alpha.x)
+
+| Package                             | Old Version      | New Version        |
+| ----------------------------------- | ---------------- | ------------------ |
+| `@admin-layout/assets`              | 12.0.16-alpha.36 | **12.2.1-alpha.0** |
+| `@admin-layout/tailwind-design-pro` | 12.0.16-alpha.68 | **12.2.1-alpha.5** |
+
+## Changes Applied
+
+### 1. **Entry Client** (`src/entry.client.tsx`)
+
+- ✅ Removed `StrictMode` wrapper from hydration
+- ✅ Removed `CacheProvider` from `@emotion/react`
+- ✅ Removed `createEmotionCache` import and usage
+- ✅ Simplified hydration without emotion wrapper
+- **Reason**: Remix 2.15.3 recommends removing StrictMode in production to avoid double-rendering issues. Emotion is no longer needed for SSR styling.
+
+### 2. **Entry Server** (`src/entry.server.tsx`)
+
+- ✅ Removed deprecated `abortDelay` prop from `RemixServer`
+- ✅ Changed `ABORT_DELAY` constant to exported `streamTimeout`
+- ✅ Removed `CacheProvider` from `@emotion/react`
+- ✅ Removed `renderStylesToNodeStream` from `@emotion/server`
+- ✅ Removed `createEmotionCache` import and usage
+- ✅ Updated timeout to `streamTimeout + 1000`
+- ✅ Simplified rendering pipeline without emotion styles
+- **Reason**: `abortDelay` is deprecated in Remix 2.15.3, replaced by `streamTimeout` pattern. Emotion SSR is no longer needed.
+
+### 3. **Server Configuration** (`server.js`)
+
+- ✅ Removed `installGlobals()` - Not needed with Node.js 20+ (native `Response.json()` support)
+- ✅ Removed unused imports: `readFileSync`, `fileURLToPath`, `dirname`, `join`
+- ✅ Updated JSON import syntax from `JSON.parse(readFileSync(...))` to `import config from '...' with { type: 'json' }`
+- ✅ Added `.well-known/*` handler to ignore Chrome DevTools requests
+- **Reason**: ES2024 standard compliance (Node.js 20.10+), cleaner code
+
+**Important**: Requires Node.js 20+ for native `Response.json()` support. Use `nvm use 22` to ensure compatibility.
+
+### 4. **Vite Configuration** (`vite.config.ts`)
+
+- ✅ **Removed `routes: routesConfig`** - Must use `routes.ts` file instead (v3_routeConfig flag requires this)
+- ✅ **Removed `installGlobals()`** - Not needed with Node.js 20+ (native `Response.json()` support)
+- ✅ Removed unused imports: `readFileSync`, `postcss`, `defineRoutesConfig`, `performCopyOperations`
+- ✅ Updated JSON import syntax to `with` clause: `import config from './app/cde-webconfig.json' with { type: 'json' }`
+- ✅ Added Future module declaration for `v3_singleFetch` type support
+- ✅ Added v3 future flags:
+    ```typescript
+    future: {
+      unstable_optimizeDeps: true,
+      v3_fetcherPersist: true,
+      v3_relativeSplatPath: true,
+      v3_throwAbortReason: true,
+      v3_singleFetch: true,
+      v3_lazyRouteDiscovery: true,
+      v3_routeConfig: true,
+    }
+    ```
+- ✅ Added `optimizeDeps.include` for Radix UI packages pre-bundling
+- ✅ Added `optimizeDeps.force: true` for better dependency optimization
+- ✅ Updated `ssr.noExternal` with more Radix UI packages for proper SSR
+- ✅ Updated `cjsInterop` dependencies to include `@rjsf/**`, `react-timer-hook`, `@ant-design/icons`, etc.
+- ✅ Added `worker.format: 'es'` for ES module workers
+
+**Important**: The `routes` config option is NOT supported when a `routes.ts` file is present. You must remove `routes: routesConfig` from vite.config.ts and migrate routes to `routes.ts`.
+
+### 5. **Route Configuration** (`src/routes.ts`)
+
+- ✅ **NEW FILE**: Created v3 route configuration file
+- Uses `remixRoutesOptionAdapter` for file-based routing
+- Integrates with existing `defineRoutesConfig` from `@common-stack/rollup-vite-utils`
+- Handles production copy operations and sync-meta.json loading
+
+## Packages Added
+
+**Location**: `servers/frontend-server/package.json` (devDependencies)
+
+```json
+{
+    "devDependencies": {
+        "@remix-run/dev": "~2.15.3",
+        "@remix-run/fs-routes": "~2.15.3",
+        "@remix-run/route-config": "~2.15.3",
+        "@remix-run/routes-option-adapter": "~2.15.3",
+        "@remix-run/serve": "~2.15.3"
+    }
+}
+```
+
+These packages enable the v3 routing configuration system.
+
+**Important**: The `@remix-run/fs-routes` package is required to prevent "Response.json is not a function" errors in Remix 2.15.3.
+
+**Note**: These should be added to the frontend-server's package.json, NOT the root workspace package.json. This follows the pattern used in adminIde-stack.
+
+## Files Modified
+
+1. `src/entry.client.tsx` - Client hydration entry point
+2. `src/entry.server.tsx` - Server rendering entry point
+3. `server.js` - Express server configuration
+4. `vite.config.ts` - Vite build configuration
+5. `src/routes.ts` - **NEW**: v3 route configuration
+6. `src/root.tsx` - Updated to match adminide-stack (imports, data function, Layout updates)
+
+## Additional Configuration Updates
+
+### Root `package.json` Updates
+
+- Added `@common-stack/codegen-zod`: `^8.2.2-alpha.0` to devDependencies
+- Added `zod`: `^4.0.0` to resolutions
+- Added `postcss`: `^8.5.1` to resolutions
+- Updated `prettier`: `^2.7.1` → `^3.4.0`
+
+### `cdecode-config.json` Updates
+
+- Added Zod schema generation configuration
+- Added `generated-zod-schemas.ts` output with `@common-stack/codegen-zod/graphql` plugin
+- Added `serviceSchemas` configuration for service schema generation
+- Added hook for running `generateAllServiceSchemas.js` after codegen
+- Simplified schema/document paths to use `%discoveredSchemas%` and `%discoveredDocuments%`
+
+### `src/root.tsx` Updates (matching adminide-stack)
+
+- Changed import from `json` to `data` from `@remix-run/react`
+- Added `useLoaderData`, `useRouteError` imports
+- Changed `ErrorBoundary` to use `ApplicationErrorHandler, RemixErrorBoundary as ErrorBoundary` from `@admin-layout/tailwind-ui`
+- Added error handling for settings loader with try/catch block
+- Renamed loader data variable to `loaderData` with proper typing `{ locale: any; __ENV__?: any }`
+- Added fallback `|| 'en'` for locale
+- Updated `__ENV__` serialization with `|| {}` for safety
+- Added Symbol.observable polyfill in `<head>` section (CRITICAL: must load before other scripts)
+- Wrapped `App` component with `ApplicationErrorHandler` component
+
+## Verification Steps
+
+1. ✅ TypeScript compilation: No errors
+2. ✅ Package installation: Both routing packages installed successfully
+3. ✅ Syntax validation: All files pass linting
+4. ✅ Future flags: All 6 v3 flags enabled
+
+## Next Steps
+
+1. **Install dependencies**:
+
+    ```bash
+    # From the root of yantra-stack
+    yarn
+
+    # Then run the dependency update script to ensure all deps are aligned
+    node tools/update-dependencies.mjs
+    ```
+
+2. **Test the application**:
+
+    ```bash
+    cd servers/frontend-server
+    yarn dev
+    ```
+
+3. **Verify routing**:
+    - Ensure all routes load correctly
+    - Check for any console warnings/errors
+    - Test navigation between routes
+
+4. **Monitor for issues**:
+    - Check for hydration mismatches
+    - Verify SSR works correctly
+    - Test dynamic route loading
+
+## References
+
+- Main upgrade guide: `/common-stack/REMIX_2.15.3_UPGRADE_GUIDE.md`
+- Remix 2.15.3 release notes: https://github.com/remix-run/remix/releases/tag/remix%402.15.3
+- Future flags documentation: https://remix.run/docs/en/v2/start/future-flags
+
+## Compatibility Requirements
+
+**Node.js Version**: 20+ required (22 recommended)
+
+- Use `nvm use 22` before running the application
+- Node.js 20+ has native `Response.json()` support, eliminating the need for `installGlobals()`
+
+**Minimum Package Versions** (from main upgrade guide):
+
+- `common-stack`: 8.2.2-alpha.0 or greater
+- `adminide-stack`: 13.0.4-alpha.0 or greater
+- `admin-layout`: 12.2.1-alpha.0 or greater
+
+All packages must be updated to these minimum versions to ensure compatibility.
+
+---
+
+## Docker Configuration Updates
+
+### `Dockerfile` Updates
+
+The Dockerfile must be updated to use Node.js 22 base image:
+
+```dockerfile
+# Before
+FROM node:20-alpine AS base
+
+# After
+FROM node:22-alpine AS base
+```
+
+**All Dockerfile stages must use Node.js 22:**
+
+```dockerfile
+# Build stage
+FROM node:22-alpine AS builder
+
+# Production stage
+FROM node:22-alpine AS production
+
+# Development stage (if applicable)
+FROM node:22-alpine AS development
+```
+
+**Reason**: Node.js 22+ is required for:
+
+- Native `Response.json()` support (eliminates need for `installGlobals()`)
+- ES2024 `import ... with { type: 'json' }` syntax support
+- Remix 2.15.3 v3 future flags compatibility
+
+---
+
+## Jenkins Configuration Updates
+
+### `Jenkinsfile` Updates
+
+- ✅ Updated `NODEJS_TOOL_VERSION` default to `nodejs22` (was `nodejs20`)
+- ✅ Added `nodejs24` as an option for future compatibility
+
+```groovy
+choice choices: ['nodejs22', 'nodejs20', 'nodejs24'], description: 'Choose NodeJS version', name: 'NODEJS_TOOL_VERSION'
+```
+
+### Jenkins Build Configuration
+
+Ensure all Jenkins build pipelines use Node.js 22:
+
+```groovy
+// In Jenkinsfile or pipeline script
+tools {
+    nodejs 'nodejs22'
+}
+
+// Or using nvm
+stages {
+    stage('Setup') {
+        steps {
+            sh 'nvm use 22'
+        }
+    }
+}
+```
+
+**Reason**: Node.js 22+ is required for native `Response.json()` support in Remix 2.15.3.
+
+---
+
+## CRITICAL: Loader Migration (`json` → `data`)
+
+### Breaking Change in Remix 2.15.3
+
+With `v3_singleFetch` future flag enabled, all loaders must migrate from using `json()` to `data()`:
+
+```typescript
+// ❌ OLD - Will cause issues with v3_singleFetch
+import { json } from '@remix-run/react';
+
+export const loader = async () => {
+    return json({ message: 'Hello' });
+};
+
+// ✅ NEW - Required for Remix 2.15.3
+import { data } from '@remix-run/react';
+
+export const loader = async () => {
+    return data({ message: 'Hello' });
+};
+```
+
+### Files That Need Migration
+
+Search your codebase for all files using `json` from `@remix-run/react` or `@remix-run/node`:
+
+```bash
+# Find all files using json import
+grep -r "import.*json.*from '@remix-run" --include="*.tsx" --include="*.ts" packages/ servers/
+
+# Find all files using json() in loaders
+grep -r "return json(" --include="*.tsx" --include="*.ts" packages/ servers/
+```
+
+### Common Locations to Check
+
+1. **Route files** (`routes/*.tsx`)
+2. **Root layout** (`root.tsx`)
+3. **Package route modules** (e.g., `packages/*/browser/src/routes/*.tsx`)
+4. **Server loaders** (any file with `loader` export)
+5. **Action handlers** (any file with `action` export)
+
+### Migration Pattern
+
+```typescript
+// Before
+import { json, useLoaderData } from '@remix-run/react';
+
+export const loader = async ({ request, context, params }) => {
+    const data = await fetchData();
+    return json(
+        { data },
+        {
+            headers: {
+                'Cache-Control': 'max-age=300',
+            },
+        },
+    );
+};
+
+// After
+import { data, useLoaderData } from '@remix-run/react';
+
+export const loader = async ({ request, context, params }) => {
+    const result = await fetchData();
+    return data(
+        { data: result },
+        {
+            headers: [['Cache-Control', 'max-age=300']],
+        },
+    );
+};
+```
+
+### Headers Format Change
+
+Note that headers format also changes with `data()`:
+
+```typescript
+// ❌ OLD with json() - Object format
+return json(data, {
+    headers: {
+        'Cache-Control': 'max-age=300',
+        'Set-Cookie': cookie,
+    },
+});
+
+// ✅ NEW with data() - Array of tuples format
+return data(result, {
+    headers: [
+        ['Cache-Control', 'max-age=300'],
+        ['Set-Cookie', cookie],
+    ],
+});
+
+// ✅ With conditional headers
+return data(result, {
+    headers: [['Cache-Control', 'max-age=300'], cookie ? ['Set-Cookie', cookie] : null].filter(Boolean) as [
+        string,
+        string,
+    ][],
+});
+```
+
+### Packages Requiring Loader Updates
+
+The following packages commonly have loaders that need migration:
+
+| Package                                      | Files to Check   |
+| -------------------------------------------- | ---------------- |
+| `@adminide-stack/account-api-browser`        | Route loaders    |
+| `@adminide-stack/platform-browser`           | Route loaders    |
+| `@adminide-stack/project-mgmt-browser`       | Route loaders    |
+| `@adminide-stack/user-auth0-browser`         | Route loaders    |
+| `@adminide-stack/extension-module-browser`   | Route loaders    |
+| `@adminide-stack/marketplace-module-browser` | Route loaders    |
+| `@admin-layout/client`                       | Settings loaders |
+| Local `packages/*/browser`                   | All route files  |
+
+### Verification
+
+After migration, verify no `json` imports remain:
+
+```bash
+# Should return no results
+grep -r "import.*{ json" --include="*.tsx" --include="*.ts" packages/ servers/ | grep -v "node_modules"
+
+# Also check for json from @remix-run/node
+grep -r "json.*from '@remix-run/node'" --include="*.tsx" --include="*.ts" packages/ servers/ | grep -v "node_modules"
+```
+
+---
+
+## Complete File Contents
+
+### `server.js`
+
+```javascript
+import express from 'express';
+import compression from 'compression';
+import { createRequestHandler } from '@remix-run/express';
+import './env.js';
+import { performCopyOperations } from '@common-stack/rollup-vite-utils/lib/preStartup/configLoader/configLoader.js';
+import config from './app/cde-webconfig.json' with { type: 'json' };
+
+Object.keys(config.buildConfig).forEach((key) => {
+    global[key] = config.buildConfig[key];
+});
+
+const startServer = async () => {
+    await performCopyOperations(config);
+
+    const { corsMiddleware } = await import(
+        `./${config.commonPaths.appPath}/${config.commonPaths.frontendStackPath}/backend/middlewares/cors.js`
+    );
+    const { containerMiddleware } = await import(
+        `./${config.commonPaths.appPath}/${config.commonPaths.frontendStackPath}/backend/middlewares/container.js`
+    );
+    const { loadContext } = await import(
+        `./${config.commonPaths.appPath}/${config.commonPaths.frontendStackPath}/load-context.server.js`
+    );
+
+    const viteDevServer =
+        process.env.NODE_ENV === 'production'
+            ? undefined
+            : await import('vite').then((vite) => {
+                  return vite.createServer({
+                      server: { middlewareMode: true },
+                  });
+              });
+
+    const remixHandler = createRequestHandler({
+        getLoadContext: loadContext,
+        build: viteDevServer
+            ? () => viteDevServer.ssrLoadModule('virtual:remix/server-build')
+            : await import('./build/server/index.js'),
+    });
+
+    const app = express();
+
+    app.use(compression());
+    app.disable('x-powered-by');
+
+    if (viteDevServer) {
+        app.use(viteDevServer.middlewares);
+    } else {
+        app.use('/assets', express.static('build/client/assets', { immutable: true, maxAge: '1y' }));
+    }
+
+    app.use(express.static('build/client', { maxAge: '1h' }));
+
+    app.use(corsMiddleware);
+    app.options('*', corsMiddleware);
+
+    // Ignore Chrome DevTools and other well-known requests
+    app.get('/.well-known/*', (req, res) => {
+        res.status(404).json({ error: 'Not found' });
+    });
+    app.use(async (req, res, next) => {
+        let isAssetRequest = (url) =>
+            /\.[jt]sx?$/.test(url) ||
+            /@id\/__x00__virtual:/.test(url) ||
+            /@vite\/client/.test(url) ||
+            /node_modules\/vite\/dist\/client\/env/.test(url);
+
+        if (isAssetRequest(req.url)) {
+            next();
+        } else {
+            return await containerMiddleware(req, res, async () => {
+                return remixHandler(req, res, next);
+            });
+        }
+    });
+
+    const port = process.env.PORT || 3000;
+    app.listen(port, () => console.log(`Express server listening at http://localhost:${port}`));
+};
+
+startServer().catch((err) => {
+    console.error('Failed to start server:', err);
+});
+```
+
+### `vite.config.ts`
+
+```typescript
+import { defineConfig, ConfigEnv, UserConfig } from 'vite';
+import { vitePlugin as remix } from '@remix-run/dev';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+// import { remixDevTools } from 'remix-development-tools';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { i18nInternationalizationPlugin } from '@common-stack/rollup-vite-utils/lib/vite-plugins/i18n-internationalization-plugin.js';
+// import { visualizer } from 'rollup-plugin-visualizer';
+import { loadEnvConfig } from '@common-stack/rollup-vite-utils/lib/preStartup/configLoader/envLoader.js';
+import { cjsInterop } from 'vite-plugin-cjs-interop';
+import { mergeWith } from 'lodash-es';
+import config from './app/cde-webconfig.json' with { type: 'json' };
+
+declare module '@remix-run/node' {
+    // or cloudflare, deno, etc.
+    interface Future {
+        v3_singleFetch: true;
+    }
+}
+
+const directoryName = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig(async ({ isSsrBuild }: ConfigEnv): Promise<UserConfig> => {
+    console.log('--- IS SSR BUILD:', isSsrBuild);
+
+    // Load environment variables from dotenv or other config
+    const dotEnvResult = loadEnvConfig(directoryName);
+
+    // Define environment variables for Vite
+    const envVariables = {
+        __ENV__: JSON.stringify(dotEnvResult?.parsed),
+        __SERVER__: true,
+        __CLIENT__: false,
+        ...Object.fromEntries(
+            Object.entries(config.buildConfig).map(([key, value]) => [
+                key,
+                typeof value === 'string' ? `"${value.replace(/\\/g, '\\\\')}"` : value,
+            ]),
+        ),
+    };
+
+    // Vite configuration
+    const viteConfig = {
+        define: envVariables,
+        ssr: {
+            // Keep small client-only libraries bundled, including all @radix-ui packages
+            // to ensure proper CommonJS to ESM interop handled by cjsInterop plugin
+            noExternal: [
+                'react-datepicker',
+                /^@radix-ui\//,
+                '@radix-ui/react-slot',
+                '@radix-ui/react-primitive',
+                '@radix-ui/react-compose-refs',
+                '@radix-ui/react-context',
+                '@radix-ui/react-collection',
+                '@radix-ui/react-separator',
+            ],
+        },
+        plugins: [
+            // remixDevTools({
+            //     server: {
+            //         logs: {
+            //             cookies: true,
+            //             defer: true,
+            //             actions: true,
+            //             loaders: true,
+            //             cache: true,
+            //             siteClear: true,
+            //         },
+            //     },
+            // }),
+            i18nInternationalizationPlugin({
+                folderName: 'cdm-locales',
+                packages: [...config.modules, ...config.i18n.packages],
+                namespaceResolution: 'basename' as any,
+            }),
+            // visualizer({
+            //     open: true,
+            //     filename: 'bundle-analysis.html',
+            // }),
+            cjsInterop({
+                dependencies: [
+                    '@rjsf/**',
+                    'react-timer-hook',
+                    'rc-util/lib/hooks/useMergedState.js',
+                    '@ant-design/icons',
+                    'rc-picker',
+                    '@monaco-editor/loader',
+                    'react-google-calendar-api',
+                    '@apollo/client',
+                ],
+            }),
+            remix({
+                appDirectory: 'src',
+                // routes: routesConfig, // Removed - using routes.ts instead
+                future: {
+                    unstable_optimizeDeps: true,
+                    v3_fetcherPersist: true,
+                    v3_relativeSplatPath: true,
+                    v3_throwAbortReason: true,
+                    v3_lazyRouteDiscovery: true,
+                    v3_singleFetch: true,
+                    v3_routeConfig: true,
+                },
+            }),
+            tsconfigPaths({ ignoreConfigErrors: true }),
+        ],
+        optimizeDeps: {
+            include: [
+                '@radix-ui/react-slot',
+                '@radix-ui/react-compose-refs',
+                '@radix-ui/react-primitive',
+                '@radix-ui/react-collection',
+                '@radix-ui/react-dialog',
+                '@radix-ui/react-select',
+                '@radix-ui/react-alert-dialog',
+                '@radix-ui/react-popover',
+                '@radix-ui/react-tooltip',
+                '@radix-ui/react-context-menu',
+            ],
+            esbuildOptions: {
+                target: 'esnext',
+            },
+            force: true, // Force dependency optimization on every build
+        },
+        build: {
+            target: 'esnext',
+            rollupOptions: {
+                output: {
+                    // Ensure that worker files are properly bundled
+                    format: 'es',
+                },
+            },
+        },
+        resolve: {
+            alias: {
+                '@app': resolve(directoryName, 'app'),
+                '@src': resolve(directoryName, 'src'),
+            },
+        },
+        worker: {
+            format: 'es', // Use ES modules format for workers
+            plugins: () => [], // Return an empty array of plugins
+        },
+    };
+
+    // Deep merge custom Vite config from config.json
+    // to merge Arrays properly need to concat.
+    const result = mergeWith(config.viteConfig, viteConfig, (objValue, srcValue) => {
+        if (Array.isArray(objValue)) {
+            return objValue.concat(srcValue);
+        }
+    });
+    return result as UserConfig;
+});
+```
+
+### `src/routes.ts`
+
+```typescript
+import { type RouteConfig } from '@remix-run/route-config';
+import { remixRoutesOptionAdapter } from '@remix-run/routes-option-adapter';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { defineRoutesConfig } from '@common-stack/rollup-vite-utils/lib/vite-wrappers/json-wrappers.js';
+import { performCopyOperations } from '@common-stack/rollup-vite-utils/lib/preStartup/configLoader/configLoader.js';
+import config from '../app/cde-webconfig.json' with { type: 'json' };
+
+const directoryName = dirname(fileURLToPath(import.meta.url));
+
+export default remixRoutesOptionAdapter(async (defineRoutes) => {
+    if (process.env.NODE_ENV === 'production') {
+        await performCopyOperations(config);
+    }
+    let metaJson = null;
+    try {
+        metaJson = await import('../app/sync-meta.json');
+    } catch {
+        console.warn('No sync-meta.json found, continuing without metadata.');
+    }
+    return defineRoutes((routeFn) => {
+        defineRoutesConfig(
+            routeFn,
+            {
+                routesFileName: 'routes.json',
+                packages: config.modules,
+                paths: config.paths,
+                iconsRepository: config?.iconsRepository,
+                rootPath: resolve(directoryName, '../../..'),
+                settings: {
+                    _useFutureCommonPackage: true,
+                },
+            },
+            metaJson,
+        );
+    });
+}) satisfies RouteConfig;
+```
+
+### `src/entry.client.tsx`
+
+```tsx
+/**
+ * By default, Remix will handle hydrating your app on the client for you.
+ * You are free to delete this file if you'd like to, but if you ever want it revealed again, you can run `npx remix reveal` ✨
+ * For more information, see https://remix.run/file-conventions/entry.client
+ */
+import * as React from 'react';
+import 'reflect-metadata';
+import { RemixBrowser } from '@remix-run/react';
+import { startTransition, StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { ApolloProvider } from '@apollo/client/index.js';
+import { SlotFillProvider, removeUniversalPortals } from '@common-stack/components-pro';
+import { InversifyProvider } from '@common-stack/client-react';
+import { Provider as ReduxProvider } from 'react-redux';
+import i18next from 'i18next';
+import { I18nextProvider, initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import Backend from 'i18next-http-backend';
+// @ts-ignore
+import { getInitialNamespaces } from 'remix-i18next/client';
+// @ts-ignore
+import { createReduxStore } from '@app/frontend-stack-react/config/redux-config.js';
+// @ts-ignore
+import { createClientContainer } from '@app/frontend-stack-react/config/client.service';
+// @ts-ignore
+import clientModules from '@app/frontend-stack-react/modules.js';
+// @ts-ignore
+import config from '@app/cde-webconfig.json';
+
+const { apolloClient: client, container, serviceFunc } = createClientContainer();
+const { store } = createReduxStore(client, serviceFunc(), container);
+
+(window as any).__remixStore = store;
+removeUniversalPortals((window as any).__SLOT_FILLS__ || []);
+
+async function hydrate() {
+    if (!i18next.isInitialized && config.i18n.enabled) {
+        await i18next
+            .use(initReactI18next)
+            .use(LanguageDetector)
+            .use(Backend)
+            .init({
+                fallbackLng: config.i18n.fallbackLng,
+                defaultNS: config.i18n.defaultNS,
+                react: config.i18n.react,
+                supportedLngs: config.i18n.supportedLngs,
+                backend: config.i18n.backend,
+                ns: getInitialNamespaces(),
+                detection: {
+                    order: ['htmlTag'],
+                    caches: [],
+                },
+            });
+    }
+    startTransition(() => {
+        hydrateRoot(
+            document,
+            <I18nextProvider i18n={i18next}>
+                <ReduxProvider store={store}>
+                    <SlotFillProvider>
+                        <InversifyProvider container={container} modules={clientModules}>
+                            <ApolloProvider client={client}>
+                                <RemixBrowser />
+                            </ApolloProvider>
+                        </InversifyProvider>
+                    </SlotFillProvider>
+                </ReduxProvider>
+            </I18nextProvider>,
+        );
+    });
+}
+
+if (window.requestIdleCallback) {
+    window.requestIdleCallback(hydrate);
+} else {
+    // Safari doesn't support requestIdleCallback
+    // https://caniuse.com/requestidlecallback
+    window.setTimeout(hydrate, 1);
+}
+```
+
+### `src/entry.server.tsx`
+
+```tsx
+/**
+ * By default, Remix will handle generating the HTTP Response for you.
+ * You are free to delete this file if you'd like to, but if you ever want it revealed again, you can run `npx remix reveal` ✨
+ * For more information, see https://remix.run/file-conventions/entry.server
+ */
+import * as React from 'react';
+import 'reflect-metadata';
+(global as any).__CLIENT__ = false;
+(global as any).__SERVER__ = true;
+import { PassThrough, Transform } from 'node:stream';
+import type { EntryContext } from '@remix-run/node';
+import { createReadableStreamFromReadable } from '@remix-run/node';
+import { RemixServer } from '@remix-run/react';
+import { isbot } from 'isbot';
+import { ApolloProvider } from '@apollo/client/index.js';
+import { SlotFillProvider } from '@common-stack/components-pro';
+import { InversifyProvider } from '@common-stack/client-react';
+import { renderToPipeableStream } from 'react-dom/server';
+import { Provider as ReduxProvider } from 'react-redux';
+import { LOCATION_CHANGE } from '@common-stack/remix-router-redux';
+import serialize from 'serialize-javascript';
+import { createInstance } from 'i18next';
+import { I18nextProvider, initReactI18next } from 'react-i18next';
+import Backend from 'i18next-fs-backend';
+import { resolve } from 'node:path';
+// @ts-ignore
+import { i18nextInstance as i18next } from '@app/frontend-stack-react/i18n-localization/i18next.server.js';
+import config from '@app/cde-webconfig.json';
+// @ts-ignore
+import type { IAppLoadContext } from '@common-stack/client-core';
+
+// Reject/cancel all pending promises after 5 seconds
+export const streamTimeout = 5000;
+
+class ConstantsTransform extends Transform {
+    _fills: string[];
+    _apolloState: any;
+    _reduxState: any;
+    _styleSheet: string;
+
+    constructor(fills: string[], apolloState: any, reduxState: any, styleSheet: any) {
+        super();
+        this._fills = fills;
+        this._apolloState = apolloState;
+        this._reduxState = reduxState;
+        this._styleSheet = styleSheet;
+    }
+
+    _transform(chunk, encoding, callback) {
+        let transformedChunk = chunk.toString();
+
+        if (transformedChunk.includes('[__APOLLO_STATE__]')) {
+            transformedChunk = transformedChunk.replace(
+                '[__APOLLO_STATE__]',
+                serialize(this._apolloState, { isJSON: true }),
+            );
+        }
+        if (transformedChunk.includes('[__PRELOADED_STATE__]')) {
+            transformedChunk = transformedChunk.replace(
+                '[__PRELOADED_STATE__]',
+                serialize(this._reduxState, { isJSON: true }),
+            );
+        }
+        if (transformedChunk.includes('[__SLOT_FILLS__]')) {
+            transformedChunk = transformedChunk.replace('[__SLOT_FILLS__]', serialize(this._fills, { isJSON: true }));
+        }
+        if (transformedChunk.includes('[__STYLESHEET__]')) {
+            transformedChunk = transformedChunk.replace('[__STYLESHEET__]', this._styleSheet);
+        }
+
+        callback(null, transformedChunk);
+    }
+}
+
+export default async function handleRequest(
+    request: Request,
+    responseStatusCode: number,
+    responseHeaders: Headers,
+    remixContext: EntryContext,
+    // This is ignored so we can keep it in the template for visibility.  Feel
+    // free to delete this parameter in your app if you're not using it!
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    loadContext: IAppLoadContext,
+) {
+    const instance = createInstance();
+    const lng = await i18next.getLocale(request);
+    const ns = i18next.getRouteNamespaces(remixContext);
+
+    // First, we create a new instance of i18next so every request will have a
+    // completely unique instance and not share any state.
+    if (config.i18n.enabled) {
+        await instance
+            .use(initReactI18next) // Tell our instance to use react-i18next
+            .use(Backend) // Setup our backend.init({
+            .init({
+                fallbackLng: config.i18n.fallbackLng,
+                defaultNS: config.i18n.defaultNS,
+                react: config.i18n.react,
+                supportedLngs: config.i18n.supportedLngs,
+                lng, // The locale we detected above
+                ns, // The namespaces the routes about to render want to use
+                backend: {
+                    loadPath: resolve(config.i18n.backend.loadServerPath),
+                },
+            });
+    }
+
+    return isbot(request.headers.get('user-agent') || '')
+        ? handleBotRequest(request, responseStatusCode, responseHeaders, remixContext, loadContext, instance)
+        : handleBrowserRequest(request, responseStatusCode, responseHeaders, remixContext, loadContext, instance);
+}
+
+function handleBotRequest(
+    request: Request,
+    responseStatusCode: number,
+    responseHeaders: Headers,
+    remixContext: EntryContext,
+    loadContext: IAppLoadContext,
+    i18nInstance: i18next,
+) {
+    return new Promise((resolve, reject) => {
+        let shellRendered = false;
+        const { pipe, abort } = renderToPipeableStream(
+            <I18nextProvider i18n={i18nInstance}>
+                <RemixServer context={remixContext} url={request.url} />
+            </I18nextProvider>,
+            {
+                onAllReady() {
+                    shellRendered = true;
+                    const body = new PassThrough();
+                    const stream = createReadableStreamFromReadable(body);
+
+                    responseHeaders.set('Content-Type', 'text/html');
+
+                    resolve(
+                        new Response(stream, {
+                            headers: responseHeaders,
+                            status: responseStatusCode,
+                        }),
+                    );
+
+                    pipe(body);
+                },
+                onShellError(error: unknown) {
+                    reject(error);
+                },
+                onError(error: unknown) {
+                    responseStatusCode = 500;
+                    // Log streaming rendering errors from inside the shell.  Don't log
+                    // errors encountered during initial shell rendering since they'll
+                    // reject and get logged in handleDocumentRequest.
+                    if (shellRendered) {
+                        console.error(error);
+                    }
+                },
+            },
+        );
+
+        setTimeout(abort, streamTimeout + 1000);
+    });
+}
+
+function handleBrowserRequest(
+    request: Request,
+    responseStatusCode: number,
+    responseHeaders: Headers,
+    remixContext: EntryContext,
+    loadContext: IAppLoadContext,
+    i18nInstance: i18next,
+) {
+    return new Promise((resolve, reject) => {
+        let shellRendered = false;
+        const slotFillContext = { fills: {} };
+        const { modules: clientModules, container, apolloClient: client, store } = loadContext;
+
+        const { pathname, search, hash } = new URL(request.url);
+        store.dispatch({
+            type: LOCATION_CHANGE,
+            payload: { location: { pathname, search, hash }, action: 'POP' },
+        });
+
+        const { pipe, abort } = renderToPipeableStream(
+            (
+                <I18nextProvider i18n={i18nInstance}>
+                    <ReduxProvider store={store}>
+                        <SlotFillProvider context={slotFillContext}>
+                            <InversifyProvider container={container} modules={clientModules as any}>
+                                <ApolloProvider client={client}>
+                                    <RemixServer context={remixContext} url={request.url} />
+                                </ApolloProvider>
+                            </InversifyProvider>
+                        </SlotFillProvider>
+                    </ReduxProvider>
+                </I18nextProvider>
+            ) as any,
+            {
+                onShellReady() {
+                    shellRendered = true;
+                    const body = new PassThrough();
+                    const stream = createReadableStreamFromReadable(body);
+                    const apolloState = { ...client.extract() };
+                    const reduxState = { ...store.getState() };
+                    const fills = Object.keys(slotFillContext.fills);
+                    const styleSheet = '';
+
+                    const transform = new ConstantsTransform(fills, apolloState, reduxState, styleSheet);
+
+                    responseHeaders.set('Content-Type', 'text/html');
+
+                    resolve(
+                        new Response(stream, {
+                            headers: responseHeaders,
+                            status: responseStatusCode,
+                        }),
+                    );
+
+                    pipe(transform).pipe(body);
+                },
+                onShellError(error: unknown) {
+                    reject(error);
+                },
+                onError(error: unknown) {
+                    responseStatusCode = 500;
+                    // Log streaming rendering errors from inside the shell.  Don't log
+                    // errors encountered during initial shell rendering since they'll
+                    // reject and get logged in handleDocumentRequest.
+                    if (shellRendered) {
+                        console.error(error);
+                    }
+                    reject(error);
+                },
+            },
+        );
+
+        setTimeout(abort, streamTimeout + 1000);
+    });
+}
+```
+
+### `src/root.tsx`
+
+```tsx
+import 'reflect-metadata';
+import * as React from 'react';
+import {
+    Links,
+    Meta,
+    Outlet,
+    Scripts,
+    ScrollRestoration,
+    useLoaderData,
+    useRouteError,
+    useRouteLoaderData,
+    data,
+} from '@remix-run/react';
+// @ts-ignore
+import publicEnv from '@src/config/public-config';
+import { PluginArea } from '@common-stack/client-react';
+import { subscribeReduxRouter } from '@common-stack/remix-router-redux';
+import { ApplicationErrorHandler, RemixErrorBoundary as ErrorBoundary } from '@admin-layout/tailwind-ui';
+// @ts-ignore
+import clientModules, { plugins } from '@app/frontend-stack-react/modules.js';
+// @ts-ignore
+import { useChangeLanguage } from 'remix-i18next/react';
+import { useTranslation } from 'react-i18next';
+// @ts-ignore
+import { i18nextInstance as i18next } from '@app/frontend-stack-react/i18n-localization/i18next.server.js';
+import { LayoutCookieProvider } from '@admin-layout/client';
+import { settingsLoaderUtil } from '@admin-layout/client/lib/components/UpdateSettings/UpdateSettings.server';
+import type { IAppLoadContext } from '@common-stack/client-core';
+import type { IResourceParams } from '@common-stack/core';
+import { FillRenderProvider, PluginsLoader } from '@common-stack/components-pro';
+
+// eslint-disable-next-line import/no-unresolved
+import styles from '../tailwind.css?url';
+
+export const links = () => [{ rel: 'stylesheet', href: styles }];
+
+export const loader = async ({
+    request,
+    context,
+    params,
+}: {
+    request: Request;
+    context: IAppLoadContext;
+    params: IResourceParams;
+}) => {
+    // Fetch settings with error handling - don't let settings failures break the app
+    let settingsResponse: any = {};
+    try {
+        settingsResponse =
+            (await settingsLoaderUtil({
+                request,
+                context,
+                params,
+            })) || {};
+    } catch (error) {
+        console.error('❌ Failed to load settings, using defaults:', error);
+        // Continue without settings - the app should still work
+    }
+
+    const [locale] = await Promise.all([i18next.getLocale(request)]);
+    const loadedPlugins = await PluginsLoader(plugins, { request, context, params });
+    return data(
+        {
+            __ENV__: publicEnv,
+            locale,
+            settings: settingsResponse?.settings || {},
+            loadedPlugins,
+        },
+        {
+            headers: [
+                ['Cache-Control', 'max-age=300, s-maxage=600'],
+                settingsResponse?.setCookie ? ['Set-Cookie', settingsResponse.setCookie] : null,
+            ].filter(Boolean) as [string, string][],
+        },
+    );
+};
+
+export const handle = {
+    i18n: ['common', 'translations', 'projects'],
+};
+
+export const shouldRevalidate = () => false;
+
+export function Layout({ children }: { children: React.ReactNode }) {
+    // useLoaderData is for happy paths with Error boundary it will fail
+    // https://github.com/remix-run/remix/issues/8951#issuecomment-1973321870
+    const loaderData = useRouteLoaderData<{ locale: any; __ENV__?: any }>('root');
+    const locale = loaderData?.locale || 'en';
+
+    const { i18n } = useTranslation();
+
+    useChangeLanguage(locale);
+
+    React.useEffect(() => {
+        subscribeReduxRouter({ store: (window as any).__remixStore, router: window.__remixRouter } as any);
+    }, []);
+
+    const getConstants = () => {
+        if (typeof window === 'undefined') {
+            return (
+                <>
+                    <script
+                        dangerouslySetInnerHTML={{
+                            __html: `window.__ENV__ = ${JSON.stringify((loaderData as any)?.__ENV__ || {})}`,
+                        }}
+                    />
+                    <script
+                        src="https://cdnjs.cloudflare.com/ajax/libs/reflect-metadata/0.1.13/Reflect.min.js"
+                        integrity="sha512-jvbPH2TH5BSZumEfOJZn9IV+5bSwwN+qG4dvthYe3KCGC3/9HmxZ4phADbt9Pfcp+XSyyfc2vGZ/RMsSUZ9tbQ=="
+                        crossOrigin="anonymous"
+                        referrerPolicy="no-referrer"
+                    ></script>
+                    <script>window.__APOLLO_STATE__=[__APOLLO_STATE__]</script>
+                    <script>window.__PRELOADED_STATE__=[__PRELOADED_STATE__]</script>
+                    <script>window.__SLOT_FILLS__=[__SLOT_FILLS__]</script>
+                    <script
+                        dangerouslySetInnerHTML={{
+                            __html: `if (global === undefined) { var global = window; }`,
+                        }}
+                    />
+                </>
+            );
+        }
+        return null;
+    };
+
+    return (
+        <html lang={locale} dir={i18n.dir()}>
+            <head>
+                <meta charSet="utf-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1" />
+                {/* CRITICAL: Load Symbol.observable polyfill BEFORE any other scripts */}
+                <script
+                    dangerouslySetInnerHTML={{
+                        __html: `
+                            (function() {
+                                if (typeof Symbol !== 'undefined' && typeof Symbol.for === 'function') {
+                                    if (!Symbol.observable) {
+                                        Symbol.observable = Symbol.for('observable');
+                                    }
+                                    console.log('[Symbol.observable polyfill] Loaded in head:', Symbol.observable);
+                                }
+                            })();
+                        `,
+                    }}
+                />
+                <Meta />
+                <Links />
+                {typeof window === 'undefined' ? `[__STYLESHEET__]` : ''}
+            </head>
+            <body>
+                <PluginArea />
+                <FillRenderProvider>{clientModules.getWrappedRoot(children)}</FillRenderProvider>
+                <ScrollRestoration />
+                <Scripts />
+                {getConstants()}
+            </body>
+        </html>
+    );
+}
+
+export default function App() {
+    return (
+        <ApplicationErrorHandler plugins={plugins}>
+            <LayoutCookieProvider>
+                <Outlet />
+            </LayoutCookieProvider>
+        </ApplicationErrorHandler>
+    );
+}
+
+export { ErrorBoundary };
+```
+
+---
+
+**Upgrade Date**: November 2025  
+**Remix Version**: 2.15.3  
+**Branch**: `feat/remix-2.15.3`  
+**Commit**: `690f644d3f112b1c52b709fbc2d77e5181a1e75c`  
+**Status**: ✅ Complete