@burdenoff/fe-libs 2026.510.126

package/src/vite/shell.config.ts

@@ -0,0 +1,233 @@
+/**
+ * Standard App Shell Vite Configuration Factory
+ *
+ * @description Creates a production-ready Vite config for app shells
+ * @version Vite 8.0.0-beta.8+
+ *
+ * Features:
+ * - Application mode with optimized chunking
+ * - Consumes microfrontends via source imports (build-time composition)
+ * - Single React instance across all linked packages
+ * - Hot reload with microfrontend source watching
+ * - Production-ready build with chunk splitting
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { createAppShellConfig } from '@burdenoff/fe-libs/vite';
+ *
+ * export default createAppShellConfig({
+ *   name: 'workspaces',
+ *   port: 5200,
+ *   microfrontends: ['auth', 'billing', 'tags', 'files'],
+ * });
+ * ```
+ */
+
+import { defineConfig, type UserConfig, type Plugin } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  type AppShellConfig,
+  STANDARD_WATCH_IGNORE,
+  APP_SHELL_PORT_MAP,
+} from "./types";
+import {
+  createContextualAliasPlugin,
+  createReactSingletonAliases,
+} from "./plugins";
+
+/**
+ * Creates a standardized Vite configuration for app shells.
+ *
+ * @param config - App shell configuration options
+ * @param configPath - The path to the vite.config.ts file (use import.meta.url)
+ * @returns Vite configuration object
+ */
+export function createAppShellConfig(
+  config: AppShellConfig,
+  configPath: string,
+): UserConfig {
+  // Resolve __dirname from the config file path
+  const __dirname =
+    typeof configPath === "string" && configPath.startsWith("file://")
+      ? dirname(fileURLToPath(configPath))
+      : configPath;
+
+  const {
+    name,
+    port = APP_SHELL_PORT_MAP[name] || 5200,
+    feLibsPath = "../../fe-libs/src",
+    microfrontends = [],
+    microfePath = "../../microfe",
+    additionalAliases = {},
+    additionalPlugins = [],
+    manualChunks = {},
+    optimizeDepsInclude = [],
+  } = config;
+
+  const resolvedFeLibsPath = resolve(__dirname, feLibsPath);
+  const resolvedMicrofePath = resolve(__dirname, microfePath);
+  const srcPath = resolve(__dirname, "./src");
+  const nodeModulesPath = resolve(__dirname, "node_modules");
+
+  // Build microfrontend path map for contextual alias resolution
+  const microfePaths: Record<string, string> = {};
+  microfrontends.forEach((mfe) => {
+    microfePaths[`microfe-${mfe}`] = resolve(
+      resolvedMicrofePath,
+      `microfe-${mfe}/src`,
+    );
+  });
+
+  // Build microfrontend aliases
+  const microfeAliases: Record<string, string> = {};
+  microfrontends.forEach((mfe) => {
+    microfeAliases[`@burdenoff/microfe-${mfe}`] = resolve(
+      resolvedMicrofePath,
+      `microfe-${mfe}/src`,
+    );
+  });
+
+  const plugins: Plugin[] = [
+    createContextualAliasPlugin({
+      feLibsPath: resolvedFeLibsPath,
+      srcPath,
+      microfePaths,
+    }),
+    react(),
+    tailwindcss(),
+    ...additionalPlugins,
+  ];
+
+  // Default manual chunks for optimal caching
+  const defaultManualChunks: Record<string, string[]> = {
+    "vendor-react": ["react", "react-dom", "react-router-dom"],
+    "vendor-apollo": ["@apollo/client", "graphql"],
+    "vendor-ui": ["lucide-react", "zustand"],
+    ...manualChunks,
+  };
+
+  return defineConfig({
+    plugins,
+
+    server: {
+      port,
+      strictPort: true,
+      headers: {
+        // Required for OAuth popup flows and SharedArrayBuffer
+        "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
+        "Cross-Origin-Embedder-Policy": "unsafe-none",
+      },
+      watch: {
+        ignored: [
+          ...STANDARD_WATCH_IGNORE,
+          // Ignore microfrontend dist outputs
+          "**/microfe/*/dist/**",
+        ],
+      },
+      // Allow serving files from linked packages
+      fs: {
+        allow: [
+          resolve(__dirname, ".."),
+          resolve(__dirname, "../.."),
+          resolvedFeLibsPath,
+          resolvedMicrofePath,
+        ],
+      },
+    },
+
+    build: {
+      // Target modern browsers
+      target: "es2022",
+
+      // Enable source maps for production debugging
+      sourcemap: true,
+
+      // Chunk size warning (500 KB)
+      chunkSizeWarningLimit: 500,
+
+      // Rolldown options (Vite 8 uses Rolldown instead of Rollup)
+      rolldownOptions: {
+        output: {
+          // Manual chunk splitting for optimal caching
+          manualChunks: defaultManualChunks,
+
+          // Consistent chunk naming for better caching
+          chunkFileNames: "chunks/[name]-[hash].js",
+          entryFileNames: "[name]-[hash].js",
+          assetFileNames: "assets/[name]-[hash].[ext]",
+        },
+      },
+
+      // Minification (Vite 8 uses Oxc minifier by default)
+      minify: true,
+    },
+
+    resolve: {
+      alias: {
+        // Force single React instance to prevent "Invalid hook call" errors
+        ...createReactSingletonAliases(nodeModulesPath),
+
+        // fe-libs source
+        "@burdenoff/fe-libs": resolvedFeLibsPath,
+
+        // Microfrontend sources
+        ...microfeAliases,
+
+        // Additional aliases
+        ...additionalAliases,
+      },
+
+      // Prevent duplicate dependencies in bundle
+      dedupe: [
+        "react",
+        "react-dom",
+        "react-router-dom",
+        "@apollo/client",
+        "graphql",
+        "zustand",
+        "@tanstack/react-query",
+      ],
+
+      // Ensure correct entry point resolution
+      mainFields: ["module", "main", "browser"],
+      conditions: ["import", "module", "default"],
+    },
+
+    // Vite 8 uses Oxc for transforms instead of esbuild
+    oxc: {
+      jsx: {
+        runtime: "automatic",
+      },
+    },
+
+    // Optimize dependencies for faster dev startup
+    optimizeDeps: {
+      include: [
+        "react",
+        "react-dom",
+        "react-dom/client",
+        "react/jsx-runtime",
+        "react/jsx-dev-runtime",
+        "react-router-dom",
+        "react-error-boundary",
+        "@apollo/client",
+        "@apollo/client/react",
+        "@apollo/client/link/context",
+        "@apollo/client/link/error",
+        "graphql",
+        "lucide-react",
+        "zustand",
+        "sonner",
+        "clsx",
+        "tailwind-merge",
+        ...optimizeDepsInclude,
+      ],
+    },
+  }) as UserConfig;
+}
+
+export default createAppShellConfig;

package/src/vite/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Vite Configuration Types for Burdenoff Microfrontends and App Shells
+ *
+ * @description Type definitions for standardized Vite configurations
+ * @version Vite 8.0.0-beta.8+
+ */
+
+import type { Plugin } from "vite";
+
+/**
+ * Microfrontend configuration options
+ */
+export interface MicrofrontendConfig {
+  /** Microfrontend name (e.g., 'tags', 'auth', 'billing') */
+  name: string;
+
+  /** Development server port (must be unique across all MFEs) */
+  port: number;
+
+  /** Entry point for library build (relative to src/) */
+  entry?: string;
+
+  /** Path to fe-libs/src (relative from the MFE root) */
+  feLibsPath?: string;
+
+  /** Additional external dependencies to exclude from bundle */
+  additionalExternals?: string[];
+
+  /** Additional resolve aliases */
+  additionalAliases?: Record<string, string>;
+
+  /** Additional Vite plugins */
+  additionalPlugins?: Plugin[];
+
+  /** Enable TypeScript declaration generation */
+  generateDts?: boolean;
+}
+
+/**
+ * App Shell configuration options
+ */
+export interface AppShellConfig {
+  /** Application name (e.g., 'workspaces', 'fluidgrids') */
+  name: string;
+
+  /** Development server port */
+  port: number;
+
+  /** Path to fe-libs/src (relative from the app root) */
+  feLibsPath?: string;
+
+  /** Microfrontends to consume (e.g., ['auth', 'billing', 'tags']) */
+  microfrontends: string[];
+
+  /** Path to microfe directory (relative from the app root) */
+  microfePath?: string;
+
+  /** Additional resolve aliases */
+  additionalAliases?: Record<string, string>;
+
+  /** Additional Vite plugins */
+  additionalPlugins?: Plugin[];
+
+  /** Manual chunks configuration */
+  manualChunks?: Record<string, string[]>;
+
+  /** Dependencies to include in optimizeDeps */
+  optimizeDepsInclude?: string[];
+}
+
+/**
+ * Standard external dependencies for microfrontends
+ * These are provided by the host app shell and should not be bundled
+ */
+export const STANDARD_MFE_EXTERNALS = [
+  // React ecosystem
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-router-dom",
+
+  // Apollo Client
+  "@apollo/client",
+  "@apollo/client/react",
+  "@apollo/client/link/error",
+  "@apollo/client/link/retry",
+  "@apollo/client/link/context",
+  "@apollo/client/core",
+  "@apollo/client/cache",
+  "graphql",
+
+  // State management
+  "zustand",
+  "zustand/middleware",
+
+  // React Query
+  "@tanstack/react-query",
+
+  // Common UI
+  "lucide-react",
+
+  // fe-libs (provided by app shell)
+  "@burdenoff/fe-libs",
+  /^@burdenoff\/fe-libs\/.*/,
+] as const;
+
+/**
+ * Standard watch ignore patterns
+ */
+export const STANDARD_WATCH_IGNORE = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/.git/**",
+  "**/coverage/**",
+  "**/.turbo/**",
+  "**/build/**",
+  "**/*.log",
+  "**/tmp/**",
+  "**/.cache/**",
+  "**/test-results/**",
+  "**/__snapshots__/**",
+  "**/.idea/**",
+  "**/.vscode/**",
+  "**/.DS_Store",
+  "**/Thumbs.db",
+] as const;
+
+/**
+ * Port assignments for microfrontends (to avoid conflicts)
+ */
+export const MFE_PORT_MAP: Record<string, number> = {
+  // Core modules (5100-5109)
+  auth: 5100,
+  rbac: 5101,
+  tenant: 5102,
+  organization: 5103,
+  billing: 5104,
+  product: 5105,
+
+  // Collaboration modules (5110-5119)
+  workspaces: 5110,
+  groups: 5111,
+  calendar: 5112,
+  files: 5113,
+  tags: 5114,
+  workflows: 5115,
+
+  // Communication modules (5120-5129)
+  notification: 5120,
+  newsletter: 5121,
+  support: 5122,
+
+  // Analytics & Insights (5130-5139)
+  analytics: 5130,
+  tours: 5131,
+
+  // Product-specific modules (5140-5149)
+  bigconsole: 5140,
+  vibecontrols: 5141,
+
+  // Utility modules (5150-5159)
+  i18n: 5150,
+  store: 5151,
+};
+
+/**
+ * Port assignments for app shells
+ */
+export const APP_SHELL_PORT_MAP: Record<string, number> = {
+  workspaces: 5200,
+  fluidgrids: 5201,
+  botlit: 5202,
+  bigconsole: 5203,
+  vibecontrols: 5204,
+};