@common-stack/core 8.2.2-alpha.1 → 8.2.4-alpha.2

package/lib/component/interfaces/rollupRouteGenerated.d.ts

@@ -4,6 +4,12 @@ export interface IRoutePageExportFlags {
     hasClientLoader?: boolean;
     hasClientAction?: boolean;
     hasComponent?: boolean;
+    /**
+     * @name Has SPA Component
+     * @description Indicates that a `.client.tsx` version of the component exists.
+     * When true and `runSPAOnly` is enabled, the `.client.tsx` file will be used.
+     */
+    hasSPAComponent?: boolean;
     hasErrorBoundary?: boolean;
     /**
      * @name Query Params Generator
@@ -25,6 +31,14 @@ export interface ILoaderReturnInfo {
 export interface IRollupBuildGenerated extends IRoutePageExportFlags {
     queries?: Record<string, string | object>;
     componentPath?: string;
+    /**
+     * @name Fallback Server Component Path
+     * @description Optional path to a server-side component to use as an SSR
+     * fallback when the primary component is client-only. This allows the
+     * generated wrappers to reference a server-safe component for server
+     * rendering while using the client component in the SPA bundle.
+     */
+    fallbackServerComponentPath?: string;
     loaderReturnInfo?: ILoaderReturnInfo;
     /**
      * @name Dialog Path

package/lib/component/interfaces/routeCompute.d.ts

@@ -37,6 +37,38 @@ export interface IRouteModule extends IMenuDataItem, IGeneratedWrapperOptions {
     component?: () => Promise<{
         default: ComponentType<any>;
     }>;
+    /**
+     * @name SPA Component
+     * @description Dynamic import of an alternative Component for SPA/Tauri mode.
+     * When running in SPA mode (settings.runSPAOnly=true), this component will be used
+     * instead of the regular `component`. Use this when you need a different component
+     * implementation that doesn't rely on server-side loaders or actions.
+     *
+     * @example
+     * {
+     *   component: () => import('./RemixAuthCallback'), // Uses server loader
+     *   spaComponent: () => import('./SPAAuthCallback'), // Client-only implementation
+     * }
+     */
+    spaComponent?: () => Promise<{
+        default: ComponentType<any>;
+    }>;
+    /**
+     * @name SPA Exclude
+     * @description When true, this route will be excluded from SPA builds.
+     * Use this for resource routes or routes that only make sense in SSR mode.
+     * Routes with isResourceRoute=true are automatically excluded from SPA builds.
+     */
+    spaExclude?: boolean;
+    /**
+     * @name Fallback Server Component
+     * @description Dynamic import of the fallback server-safe component to use during SSR
+     * when the primary component is client-only. This allows the route to render a simpler
+     * component on the server while hydrating with the full client component in the browser.
+     */
+    fallbackServerComponent?: () => Promise<{
+        default: ComponentType<any>;
+    }>;
     /**
      * @name Modal Route
      * @description Indicates if the route should be displayed as a modal.

package/lib/component/interfaces/viteSettings.d.ts

@@ -16,24 +16,116 @@
  * };
  */
 export interface IViteSettings {
+    /**
+     * When true, instructs the generator to produce client-only artifacts and
+     * avoid emitting server-side loader/action wiring (used for SPA builds).
+     */
+    runSPAOnly?: boolean;
+    /**
+     * Path to write generated wrapper files (e.g. `WrappedX-<hash>.tsx`). If
+     * not provided the generator will fall back to the `app` folder in the
+     * project root.
+     */
+    outputDir?: string;
+    /**
+     * The app directory path (where routes.ts is located). This is used to
+     * calculate relative paths for route modules. In Remix, this is typically
+     * set via `appDirectory` in the vite.config.ts remix plugin configuration.
+     * @default 'src' (relative to project root)
+     */
+    appDirectory?: string;
+    /**
+     * Disable generation of server loaders for routes. Useful to opt-out of
+     * loader wiring when the project prefers client-side data fetching.
+     */
     disableLoader?: boolean;
+    /**
+     * Disable automatic loader generation for routes with middleware requirements
+     * (auth, authority, configurations, permissions). When true, loaders will not
+     * be generated automatically even when middleware conditions are present.
+     */
+    disableLoaderMiddleware?: boolean;
+    /**
+     * Disable generation of server action handlers for routes.
+     */
     disableAction?: boolean;
+    /**
+     * Disable generation of client loader helpers. When true, client-side
+     * loader wrappers will not be emitted.
+     */
     disableClientLoader?: boolean;
+    /**
+     * Disable generation of error boundary wrappers for routes.
+     */
     disableErrorBoundary?: boolean;
+    /**
+     * Disable emitting link imports (e.g. stylesheets) for routes.
+     */
     disableLinks?: boolean;
+    /**
+     * Disable emitting meta export helpers for routes.
+     */
     disableMeta?: boolean;
+    /**
+     * Disable generation of hydrate fallback helpers used during SSR -> CSR
+     * transitions.
+     */
     disableHydrateFallback?: boolean;
+    /**
+     * Disable generation of `shouldRevalidate` helpers on routes.
+     */
     disableShouldRevalidate?: boolean;
+    /**
+     * Disable generating `handle` exports for routes.
+     */
     disableHandle?: boolean;
+    /**
+     * Disable generation of `headers` export functions for routes.
+     */
     disableHeaders?: boolean;
+    /**
+     * Disable generation of client-side action wrappers.
+     */
     disableClientAction?: boolean;
+    /**
+     * When true, the generator will omit any extra props merging into the
+     * generated wrapper component props.
+     */
     disableExtraProps?: boolean;
+    /**
+     * Disable mapping or emission of client-side middleware shims.
+     */
     disableClientMiddlewares?: boolean;
+    /**
+     * Disable server-side middleware execution for routes. When true, middleware
+     * such as auth, authority, configurations, and permissions will not be
+     * executed on the server.
+     */
+    disableMiddleware?: boolean;
+    /**
+     * Import statement for the layout component used in generated routes.tsx.
+     * Used when runSPAOnly is enabled to specify the layout wrapper component.
+     * @example "import { DashboardLayout } from '../src/layouts';"
+     */
+    layoutImport?: string;
+    /**
+     * Name of the layout component to use in generated routes.tsx.
+     * Used when runSPAOnly is enabled to wrap the routes.
+     * @default 'DashboardLayout'
+     */
+    layoutComponent?: string;
+    /**
+     * Component replacement configuration. When enabled, specific routes may
+     * be replaced with a different component path during wrapper generation.
+     */
     componentReplacement?: {
+        /** Enable component replacement feature. */
         enabled?: boolean;
+        /** Map of route key -> replacement component path. */
         replacements?: {
             [routeKey: string]: string;
         };
+        /** Routes to exclude from replacement even when a global rule exists. */
         excludeRoutes?: string[];
     };
     /**

package/lib/component/interfaces/wrapperRouteOptions.d.ts

@@ -3,8 +3,10 @@ import { IAuthorityConfig } from './authority';
 import { IRollupBuildGenerated } from './rollupRouteGenerated';
 import { IViteSettings } from './viteSettings';
 export interface IWrapperConfigPaths {
+    app?: string;
     configPermissionWrapper?: string;
     authMiddlware?: string;
+    spaAuthMiddleware?: string;
     configurationMiddlewareExec?: string;
     lifecycleMiddleware?: string;
     middlewareExec?: string;
@@ -60,6 +62,12 @@ export interface IResourceParams {
  * @description Fields missing from IWrapperOptions that exist in IOptions.
  */
 export interface IGeneratedWrapperOptions {
+    /**
+     * @name Component Name
+     * @description The standardized component name used in both the wrapper file export
+     * and the routes.tsx import to ensure consistency.
+     */
+    componentName?: string;
     /**
      * @name Wrapper Component Paths
      * @description Array of wrapper component paths for consistent layout.
@@ -70,6 +78,18 @@ export interface IGeneratedWrapperOptions {
      * @description Array of middleware functions for the route.
      */
     middlewares?: any[];
+    /**
+     * @name Has Middleware
+     * @description Indicates if the route has middleware conditions that require execution.
+     * Calculated from requireAuth, middlewares, authority, configurations, and extraPermissions.
+     */
+    hasMiddleware?: boolean;
+    /**
+     * @name Has Queries
+     * @description Indicates if the route has GraphQL queries defined.
+     * Calculated from the queries object.
+     */
+    hasQueries?: boolean;
     /**
      * @name Client Middlewares
      * @description Array of client-side middleware paths applied to the route.
@@ -122,6 +142,47 @@ export interface IGeneratedWrapperOptions {
      * @description The file path to the route's component.
      */
     componentPath?: string;
+    /**
+     * @name Generate SPA Component
+     * @description When true, instructs the rollup build process to generate a
+     * `.client.tsx` version of the component from the source `componentPath`.
+     * This auto-generated SPA component will be optimized for client-only usage.
+     */
+    generateSPAComponent?: boolean;
+    /**
+     * @name Has SPA Component
+     * @description When true, indicates that a `.client.tsx` version of the component
+     * exists alongside the main component file. In SPA-only mode (`runSPAOnly`), the
+     * generator will use the `.client.tsx` file instead of the regular component.
+     * This allows you to provide optimized client-only versions of components for
+     * SPA builds while keeping SSR-compatible versions for regular builds.
+     * @example
+     * // If componentPath is '@pkg/lib/Dashboard.js' and hasSPAComponent is true,
+     * // SPA mode will use '@pkg/lib/Dashboard.client.tsx'
+     */
+    hasSPAComponent?: boolean;
+    /**
+     * @name Client Only
+     * @description When true, indicates this route's component should be rendered
+     * only on the client (no server-side rendering). Use this when the component
+     * depends on browser globals (e.g. `window`, `document`, or third-party
+     * libraries like maps) and cannot safely run during SSR. This mirrors the
+     * `ClientOnly` pattern from `remix-utils` (render nothing on the server and
+     * hydrate on the client).
+     *
+     * For SSR safety you can provide `fallbackServerComponentPath` to render a
+     * simpler server-safe component during SSR while the real client component
+     * is used in the browser.
+     */
+    clientOnly?: boolean;
+    /**
+     * @name Fallback Server Component Path
+     * @description Optional path to a server-side component to use as an SSR
+     * fallback when the primary component is client-only. This allows the
+     * generated wrappers to reference a server-safe component for server
+     * rendering while using the client component in the SPA bundle.
+     */
+    fallbackServerComponentPath?: string;
     /**
      * @name Resource URI
      * @description URI representing the resource associated with the route.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@common-stack/core",
-    "version": "8.2.2-alpha.1",
+    "version": "8.2.4-alpha.2",
     "description": "Common core for higher packages to depend on",
     "license": "UNLICENSED",
     "author": "CDMBase LLC",
@@ -21,7 +21,7 @@
         "watch": "yarn build:lib:watch"
     },
     "devDependencies": {
-        "common": "8.2.2-alpha.0"
+        "common": "8.2.4-alpha.2"
     },
     "peerDependencies": {
         "@cdm-logger/core": ">=9.0.17"
@@ -29,7 +29,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "404d0bcb02c61d0cdeb7fd3c64d321c8b92f0a18",
+    "gitHead": "cfcc965f8ea96d4dc5ca00245c2dcca7d99f234d",
     "typescript": {
         "definition": "lib/index.d.ts"
     }