@flight-framework/core 0.5.0 → 0.6.1

package/dist/plugins/index.d.ts

@@ -0,0 +1,155 @@
+import { Plugin } from 'vite';
+import { FlightEnvPluginOptions } from './env-plugin.js';
+export { flightEnvPlugin } from './env-plugin.js';
+import { ServerBoundaryPluginOptions } from './server-boundary-plugin.js';
+export { serverBoundaryPlugin } from './server-boundary-plugin.js';
+
+/**
+ * @flight-framework/core - Critical CSS Plugin
+ *
+ * Extract and inline critical CSS for improved Core Web Vitals.
+ * Uses Critters under the hood for CSS extraction.
+ *
+ * This is an OPTIONAL plugin. Install 'critters' only if you use it.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { criticalCSS } from '@flight-framework/core/plugins';
+ *
+ * export default defineConfig({
+ *     plugins: [
+ *         criticalCSS({
+ *             preload: 'swap',
+ *             pruneSource: false,
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+
+/**
+ * Preload strategy for non-critical CSS.
+ *
+ * - 'body': Move stylesheet links to end of body
+ * - 'media': Use media="print" and swap to "all" on load
+ * - 'swap': Use link rel="preload" and swap to stylesheet
+ * - 'swap-high': Like swap, with fetchpriority="high"
+ * - 'js': Load via JavaScript
+ * - 'js-lazy': Load via JavaScript when idle
+ * - false: Don't preload
+ */
+type PreloadStrategy = 'body' | 'media' | 'swap' | 'swap-high' | 'js' | 'js-lazy' | false;
+/**
+ * Critical CSS plugin options.
+ */
+interface CriticalCSSOptions {
+    /**
+     * Enable critical CSS extraction.
+     * @default true in production
+     */
+    enabled?: boolean;
+    /**
+     * Strategy for loading non-critical CSS.
+     * @default 'swap'
+     */
+    preload?: PreloadStrategy;
+    /**
+     * Remove inlined CSS rules from the source stylesheet.
+     * Reduces duplicate CSS but may cause issues with JS frameworks.
+     * @default false
+     */
+    pruneSource?: boolean;
+    /**
+     * Remove unused CSS selectors from critical CSS.
+     * @default true
+     */
+    reduceInlineStyles?: boolean;
+    /**
+     * Merge adjacent inline <style> tags.
+     * @default true
+     */
+    mergeStylesheets?: boolean;
+    /**
+     * Additional CSS selectors to always include as critical.
+     */
+    additionalStylesheets?: string[];
+    /**
+     * CSS selectors to exclude from critical extraction.
+     */
+    excludeSelectors?: string[];
+    /**
+     * Routes to include (glob patterns).
+     * @default ['**\/*.html']
+     */
+    include?: string[];
+    /**
+     * Routes to exclude (glob patterns).
+     * @default ['/api/**']
+     */
+    exclude?: string[];
+    /**
+     * Inline external fonts.
+     * @default false
+     */
+    inlineFonts?: boolean;
+    /**
+     * Preload external fonts.
+     * @default true
+     */
+    preloadFonts?: boolean;
+    /**
+     * Maximum size of inlined CSS (in bytes).
+     * Larger stylesheets will be loaded normally.
+     * @default 100000 (100KB)
+     */
+    maxInlinedSize?: number;
+    /**
+     * Log extraction stats.
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Vite plugin for critical CSS extraction.
+ *
+ * This plugin extracts critical (above-the-fold) CSS and inlines it
+ * in the HTML, deferring non-critical CSS for better performance.
+ *
+ * Requires 'critters' as a peer dependency:
+ * ```bash
+ * npm install critters
+ * ```
+ *
+ * @param options - Plugin configuration
+ * @returns Vite plugin
+ */
+declare function criticalCSS(options?: CriticalCSSOptions): Plugin;
+
+/**
+ * @flight-framework/core - Build Plugins
+ *
+ * Optional Vite plugins for advanced optimizations.
+ * These plugins are opt-in and require explicit configuration.
+ *
+ * Flight doesn't force you to use any of these - use them if you want.
+ */
+
+/**
+ * Recommended plugins for most apps.
+ * Provides sensible defaults with warnings for violations.
+ */
+declare function flightRecommendedPlugins(options?: {
+    env?: FlightEnvPluginOptions;
+    serverBoundary?: ServerBoundaryPluginOptions;
+}): Plugin[];
+/**
+ * Strict mode plugins - errors instead of warnings.
+ * Recommended for production builds.
+ */
+declare function flightStrictPlugins(options?: {
+    env?: FlightEnvPluginOptions;
+    serverBoundary?: ServerBoundaryPluginOptions;
+}): Plugin[];
+
+export { type CriticalCSSOptions, FlightEnvPluginOptions, type PreloadStrategy, ServerBoundaryPluginOptions, criticalCSS, flightRecommendedPlugins, flightStrictPlugins };

package/dist/plugins/index.js

@@ -0,0 +1,150 @@
+import { serverBoundaryPlugin } from '../chunk-56ZZNOJD.js';
+export { serverBoundaryPlugin } from '../chunk-56ZZNOJD.js';
+import { flightEnvPlugin } from '../chunk-RFTE6JVG.js';
+export { flightEnvPlugin } from '../chunk-RFTE6JVG.js';
+
+// src/plugins/critical-css.ts
+function criticalCSS(options = {}) {
+  const {
+    preload = "swap",
+    pruneSource = false,
+    reduceInlineStyles = true,
+    mergeStylesheets = true,
+    additionalStylesheets = [],
+    inlineFonts = false,
+    preloadFonts = true,
+    maxInlinedSize = 1e5,
+    include = ["**/*.html"],
+    exclude = ["/api/**"],
+    verbose = true
+  } = options;
+  let config;
+  let isProduction = false;
+  let enabled = options.enabled;
+  let critters = null;
+  return {
+    name: "flight-critical-css",
+    enforce: "post",
+    apply: "build",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      isProduction = resolvedConfig.command === "build";
+      if (enabled === void 0) {
+        enabled = isProduction;
+      }
+    },
+    async buildStart() {
+      if (!enabled) return;
+      try {
+        const CrittersModule = await import('critters');
+        const Critters = CrittersModule.default || CrittersModule;
+        const crittersOptions = {
+          preload,
+          pruneSource,
+          reduceInlineStyles,
+          mergeStylesheets,
+          inlineFonts,
+          preloadFonts,
+          additionalStylesheets,
+          external: true,
+          noscriptFallback: true,
+          path: config.build.outDir,
+          publicPath: config.base || "/",
+          logLevel: verbose ? "info" : "silent"
+        };
+        critters = new Critters(crittersOptions);
+        if (verbose) {
+          console.log("[flight-critical-css] Critical CSS extraction enabled");
+        }
+      } catch (error) {
+        console.warn(
+          "[flight-critical-css] Critters not installed. Install with: npm install critters"
+        );
+        critters = null;
+      }
+    },
+    async transformIndexHtml(html, ctx) {
+      if (!enabled || !critters) {
+        return html;
+      }
+      const path = ctx.path || "";
+      for (const pattern of exclude) {
+        if (matchesPattern(path, pattern)) {
+          return html;
+        }
+      }
+      let shouldProcess = false;
+      for (const pattern of include) {
+        if (matchesPattern(path, pattern)) {
+          shouldProcess = true;
+          break;
+        }
+      }
+      if (!shouldProcess) {
+        return html;
+      }
+      try {
+        const processedHtml = await critters.process(html);
+        const inlineStyleMatch = processedHtml.match(/<style[^>]*>([\s\S]*?)<\/style>/gi);
+        if (inlineStyleMatch) {
+          const totalInlineSize = inlineStyleMatch.reduce(
+            (sum, style) => sum + style.length,
+            0
+          );
+          if (totalInlineSize > maxInlinedSize) {
+            console.warn(
+              `[flight-critical-css] Inline CSS (${totalInlineSize} bytes) exceeds max (${maxInlinedSize} bytes) for ${path}`
+            );
+          }
+        }
+        if (verbose) {
+          console.log(`[flight-critical-css] Processed: ${path}`);
+        }
+        return processedHtml;
+      } catch (error) {
+        console.error(`[flight-critical-css] Error processing ${path}:`, error);
+        return html;
+      }
+    },
+    async closeBundle() {
+      if (verbose && critters) {
+        console.log("[flight-critical-css] Critical CSS extraction complete");
+      }
+    }
+  };
+}
+function matchesPattern(path, pattern) {
+  const regexPattern = pattern.replace(/\*\*/g, "{{DOUBLE_STAR}}").replace(/\*/g, "[^/]*").replace(/\{\{DOUBLE_STAR\}\}/g, ".*").replace(/\?/g, ".");
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(path);
+}
+
+// src/plugins/index.ts
+function flightRecommendedPlugins(options) {
+  return [
+    flightEnvPlugin({
+      privateVarBehavior: "warn",
+      ...options?.env
+    }),
+    serverBoundaryPlugin({
+      violationBehavior: "warn",
+      ...options?.serverBoundary
+    })
+  ];
+}
+function flightStrictPlugins(options) {
+  return [
+    flightEnvPlugin({
+      privateVarBehavior: "error",
+      ...options?.env
+    }),
+    serverBoundaryPlugin({
+      violationBehavior: "error",
+      ...options?.serverBoundary
+    })
+  ];
+}
+
+export { criticalCSS, flightRecommendedPlugins, flightStrictPlugins };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugins/critical-css.ts","../../src/plugins/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\r\n * @flight-framework/core - Critical CSS Plugin\r\n *\r\n * Extract and inline critical CSS for improved Core Web Vitals.\r\n * Uses Critters under the hood for CSS extraction.\r\n *\r\n * This is an OPTIONAL plugin. Install 'critters' only if you use it.\r\n *\r\n * @example\r\n * ```typescript\r\n * // vite.config.ts\r\n * import { criticalCSS } from '@flight-framework/core/plugins';\r\n *\r\n * export default defineConfig({\r\n *     plugins: [\r\n *         criticalCSS({\r\n *             preload: 'swap',\r\n *             pruneSource: false,\r\n *         }),\r\n *     ],\r\n * });\r\n * ```\r\n */\r\n\r\nimport type { Plugin, ResolvedConfig } from 'vite';\r\n\r\n// ============================================================================\r\n// Types\r\n// ============================================================================\r\n\r\n/**\r\n * Preload strategy for non-critical CSS.\r\n *\r\n * - 'body': Move stylesheet links to end of body\r\n * - 'media': Use media=\"print\" and swap to \"all\" on load\r\n * - 'swap': Use link rel=\"preload\" and swap to stylesheet\r\n * - 'swap-high': Like swap, with fetchpriority=\"high\"\r\n * - 'js': Load via JavaScript\r\n * - 'js-lazy': Load via JavaScript when idle\r\n * - false: Don't preload\r\n */\r\nexport type PreloadStrategy =\r\n    | 'body'\r\n    | 'media'\r\n    | 'swap'\r\n    | 'swap-high'\r\n    | 'js'\r\n    | 'js-lazy'\r\n    | false;\r\n\r\n/**\r\n * Critical CSS plugin options.\r\n */\r\nexport interface CriticalCSSOptions {\r\n    /**\r\n     * Enable critical CSS extraction.\r\n     * @default true in production\r\n     */\r\n    enabled?: boolean;\r\n\r\n    /**\r\n     * Strategy for loading non-critical CSS.\r\n     * @default 'swap'\r\n     */\r\n    preload?: PreloadStrategy;\r\n\r\n    /**\r\n     * Remove inlined CSS rules from the source stylesheet.\r\n     * Reduces duplicate CSS but may cause issues with JS frameworks.\r\n     * @default false\r\n     */\r\n    pruneSource?: boolean;\r\n\r\n    /**\r\n     * Remove unused CSS selectors from critical CSS.\r\n     * @default true\r\n     */\r\n    reduceInlineStyles?: boolean;\r\n\r\n    /**\r\n     * Merge adjacent inline <style> tags.\r\n     * @default true\r\n     */\r\n    mergeStylesheets?: boolean;\r\n\r\n    /**\r\n     * Additional CSS selectors to always include as critical.\r\n     */\r\n    additionalStylesheets?: string[];\r\n\r\n    /**\r\n     * CSS selectors to exclude from critical extraction.\r\n     */\r\n    excludeSelectors?: string[];\r\n\r\n    /**\r\n     * Routes to include (glob patterns).\r\n     * @default ['**\\/*.html']\r\n     */\r\n    include?: string[];\r\n\r\n    /**\r\n     * Routes to exclude (glob patterns).\r\n     * @default ['/api/**']\r\n     */\r\n    exclude?: string[];\r\n\r\n    /**\r\n     * Inline external fonts.\r\n     * @default false\r\n     */\r\n    inlineFonts?: boolean;\r\n\r\n    /**\r\n     * Preload external fonts.\r\n     * @default true\r\n     */\r\n    preloadFonts?: boolean;\r\n\r\n    /**\r\n     * Maximum size of inlined CSS (in bytes).\r\n     * Larger stylesheets will be loaded normally.\r\n     * @default 100000 (100KB)\r\n     */\r\n    maxInlinedSize?: number;\r\n\r\n    /**\r\n     * Log extraction stats.\r\n     * @default true\r\n     */\r\n    verbose?: boolean;\r\n}\r\n\r\n// ============================================================================\r\n// Critters Integration\r\n// ============================================================================\r\n\r\n/**\r\n * Critters options interface (subset of full Critters options).\r\n * Full options available at: https://github.com/GoogleChromeLabs/critters\r\n */\r\ninterface CrittersOptions {\r\n    preload?: PreloadStrategy;\r\n    pruneSource?: boolean;\r\n    reduceInlineStyles?: boolean;\r\n    mergeStylesheets?: boolean;\r\n    external?: boolean;\r\n    inlineFonts?: boolean;\r\n    preloadFonts?: boolean;\r\n    additionalStylesheets?: string[];\r\n    noscriptFallback?: boolean;\r\n    path?: string;\r\n    publicPath?: string;\r\n    logLevel?: 'info' | 'warn' | 'error' | 'trace' | 'debug' | 'silent';\r\n}\r\n\r\n// ============================================================================\r\n// Vite Plugin\r\n// ============================================================================\r\n\r\n/**\r\n * Vite plugin for critical CSS extraction.\r\n *\r\n * This plugin extracts critical (above-the-fold) CSS and inlines it\r\n * in the HTML, deferring non-critical CSS for better performance.\r\n *\r\n * Requires 'critters' as a peer dependency:\r\n * ```bash\r\n * npm install critters\r\n * ```\r\n *\r\n * @param options - Plugin configuration\r\n * @returns Vite plugin\r\n */\r\nexport function criticalCSS(options: CriticalCSSOptions = {}): Plugin {\r\n    const {\r\n        preload = 'swap',\r\n        pruneSource = false,\r\n        reduceInlineStyles = true,\r\n        mergeStylesheets = true,\r\n        additionalStylesheets = [],\r\n        inlineFonts = false,\r\n        preloadFonts = true,\r\n        maxInlinedSize = 100000,\r\n        include = ['**/*.html'],\r\n        exclude = ['/api/**'],\r\n        verbose = true,\r\n    } = options;\r\n\r\n    let config: ResolvedConfig;\r\n    let isProduction = false;\r\n    let enabled = options.enabled;\r\n    let critters: {\r\n        process: (html: string) => Promise<string>;\r\n    } | null = null;\r\n\r\n    return {\r\n        name: 'flight-critical-css',\r\n        enforce: 'post',\r\n        apply: 'build',\r\n\r\n        configResolved(resolvedConfig) {\r\n            config = resolvedConfig;\r\n            isProduction = resolvedConfig.command === 'build';\r\n\r\n            // Enable by default only in production\r\n            if (enabled === undefined) {\r\n                enabled = isProduction;\r\n            }\r\n        },\r\n\r\n        async buildStart() {\r\n            if (!enabled) return;\r\n\r\n            try {\r\n                // Dynamic import of Critters (optional peer dependency)\r\n                // @ts-expect-error - critters has broken type exports in its package.json\r\n                const CrittersModule = await import('critters');\r\n                const Critters = CrittersModule.default || CrittersModule;\r\n\r\n                const crittersOptions: CrittersOptions = {\r\n                    preload,\r\n                    pruneSource,\r\n                    reduceInlineStyles,\r\n                    mergeStylesheets,\r\n                    inlineFonts,\r\n                    preloadFonts,\r\n                    additionalStylesheets,\r\n                    external: true,\r\n                    noscriptFallback: true,\r\n                    path: config.build.outDir,\r\n                    publicPath: config.base || '/',\r\n                    logLevel: verbose ? 'info' : 'silent',\r\n                };\r\n\r\n                critters = new Critters(crittersOptions);\r\n\r\n                if (verbose) {\r\n                    console.log('[flight-critical-css] Critical CSS extraction enabled');\r\n                }\r\n            } catch (error) {\r\n                console.warn(\r\n                    '[flight-critical-css] Critters not installed. Install with: npm install critters'\r\n                );\r\n                critters = null;\r\n            }\r\n        },\r\n\r\n        async transformIndexHtml(html, ctx) {\r\n            if (!enabled || !critters) {\r\n                return html;\r\n            }\r\n\r\n            // Check if this route should be processed\r\n            const path = ctx.path || '';\r\n\r\n            // Check exclusions\r\n            for (const pattern of exclude) {\r\n                if (matchesPattern(path, pattern)) {\r\n                    return html;\r\n                }\r\n            }\r\n\r\n            // Check inclusions\r\n            let shouldProcess = false;\r\n            for (const pattern of include) {\r\n                if (matchesPattern(path, pattern)) {\r\n                    shouldProcess = true;\r\n                    break;\r\n                }\r\n            }\r\n\r\n            if (!shouldProcess) {\r\n                return html;\r\n            }\r\n\r\n            try {\r\n                const processedHtml = await critters.process(html);\r\n\r\n                // Check if critical CSS is too large\r\n                const inlineStyleMatch = processedHtml.match(/<style[^>]*>([\\s\\S]*?)<\\/style>/gi);\r\n                if (inlineStyleMatch) {\r\n                    const totalInlineSize = inlineStyleMatch.reduce(\r\n                        (sum, style) => sum + style.length, 0\r\n                    );\r\n\r\n                    if (totalInlineSize > maxInlinedSize) {\r\n                        console.warn(\r\n                            `[flight-critical-css] Inline CSS (${totalInlineSize} bytes) exceeds max (${maxInlinedSize} bytes) for ${path}`\r\n                        );\r\n                    }\r\n                }\r\n\r\n                if (verbose) {\r\n                    console.log(`[flight-critical-css] Processed: ${path}`);\r\n                }\r\n\r\n                return processedHtml;\r\n            } catch (error) {\r\n                console.error(`[flight-critical-css] Error processing ${path}:`, error);\r\n                return html;\r\n            }\r\n        },\r\n\r\n        async closeBundle() {\r\n            if (verbose && critters) {\r\n                console.log('[flight-critical-css] Critical CSS extraction complete');\r\n            }\r\n        },\r\n    };\r\n}\r\n\r\n// ============================================================================\r\n// Helper Functions\r\n// ============================================================================\r\n\r\n/**\r\n * Simple glob pattern matching.\r\n */\r\nfunction matchesPattern(path: string, pattern: string): boolean {\r\n    // Convert glob to regex\r\n    const regexPattern = pattern\r\n        .replace(/\\*\\*/g, '{{DOUBLE_STAR}}')\r\n        .replace(/\\*/g, '[^/]*')\r\n        .replace(/\\{\\{DOUBLE_STAR\\}\\}/g, '.*')\r\n        .replace(/\\?/g, '.');\r\n\r\n    const regex = new RegExp(`^${regexPattern}$`);\r\n    return regex.test(path);\r\n}\r\n\r\n// ============================================================================\r\n// CSS Optimization Utilities\r\n// ============================================================================\r\n\r\n/**\r\n * Extract inline styles from HTML.\r\n * Utility for manual critical CSS handling.\r\n */\r\nexport function extractInlineStyles(html: string): {\r\n    html: string;\r\n    styles: string[];\r\n} {\r\n    const styles: string[] = [];\r\n    const cleanedHtml = html.replace(\r\n        /<style[^>]*>([\\s\\S]*?)<\\/style>/gi,\r\n        (match, content) => {\r\n            styles.push(content);\r\n            return '';\r\n        }\r\n    );\r\n\r\n    return { html: cleanedHtml, styles };\r\n}\r\n\r\n/**\r\n * Merge multiple CSS strings into one.\r\n */\r\nexport function mergeCSS(styles: string[]): string {\r\n    return styles\r\n        .map(s => s.trim())\r\n        .filter(Boolean)\r\n        .join('\\n');\r\n}\r\n\r\n/**\r\n * Generate a preload link for a stylesheet.\r\n */\r\nexport function generatePreloadLink(\r\n    href: string,\r\n    strategy: PreloadStrategy\r\n): string {\r\n    switch (strategy) {\r\n        case 'swap':\r\n            return `<link rel=\"preload\" href=\"${href}\" as=\"style\" onload=\"this.onload=null;this.rel='stylesheet'\">`;\r\n        case 'swap-high':\r\n            return `<link rel=\"preload\" href=\"${href}\" as=\"style\" fetchpriority=\"high\" onload=\"this.onload=null;this.rel='stylesheet'\">`;\r\n        case 'media':\r\n            return `<link rel=\"stylesheet\" href=\"${href}\" media=\"print\" onload=\"this.media='all'\">`;\r\n        case 'js':\r\n            return `<script>\r\n                (function(){var l=document.createElement('link');l.rel='stylesheet';l.href='${href}';document.head.appendChild(l);})();\r\n            </script>`;\r\n        case 'js-lazy':\r\n            return `<script>\r\n                requestIdleCallback(function(){var l=document.createElement('link');l.rel='stylesheet';l.href='${href}';document.head.appendChild(l);});\r\n            </script>`;\r\n        default:\r\n            return '';\r\n    }\r\n}\r\n\r\n/**\r\n * Generate noscript fallback for preloaded stylesheet.\r\n */\r\nexport function generateNoscriptFallback(href: string): string {\r\n    return `<noscript><link rel=\"stylesheet\" href=\"${href}\"></noscript>`;\r\n}\r\n\r\n// ============================================================================\r\n// Exports\r\n// ============================================================================\r\n\r\nexport default criticalCSS;\r\n","/**\r\n * @flight-framework/core - Build Plugins\r\n *\r\n * Optional Vite plugins for advanced optimizations.\r\n * These plugins are opt-in and require explicit configuration.\r\n * \r\n * Flight doesn't force you to use any of these - use them if you want.\r\n */\r\n\r\n// Critical CSS Plugin (existing)\r\nexport { criticalCSS } from './critical-css.js';\r\nexport type {\r\n    CriticalCSSOptions,\r\n    PreloadStrategy,\r\n} from './critical-css.js';\r\n\r\n// Environment Variables Plugin (NEW)\r\nexport {\r\n    flightEnvPlugin,\r\n    type FlightEnvPluginOptions,\r\n} from './env-plugin.js';\r\n\r\n// Server Boundary Plugin (NEW)\r\nexport {\r\n    serverBoundaryPlugin,\r\n    type ServerBoundaryPluginOptions,\r\n} from './server-boundary-plugin.js';\r\n\r\n// ============================================================================\r\n// Convenience Presets\r\n// ============================================================================\r\n\r\nimport type { Plugin } from 'vite';\r\nimport { flightEnvPlugin, type FlightEnvPluginOptions } from './env-plugin.js';\r\nimport { serverBoundaryPlugin, type ServerBoundaryPluginOptions } from './server-boundary-plugin.js';\r\n\r\n/**\r\n * Recommended plugins for most apps.\r\n * Provides sensible defaults with warnings for violations.\r\n */\r\nexport function flightRecommendedPlugins(options?: {\r\n    env?: FlightEnvPluginOptions;\r\n    serverBoundary?: ServerBoundaryPluginOptions;\r\n}): Plugin[] {\r\n    return [\r\n        flightEnvPlugin({\r\n            privateVarBehavior: 'warn',\r\n            ...options?.env,\r\n        }),\r\n        serverBoundaryPlugin({\r\n            violationBehavior: 'warn',\r\n            ...options?.serverBoundary,\r\n        }),\r\n    ];\r\n}\r\n\r\n/**\r\n * Strict mode plugins - errors instead of warnings.\r\n * Recommended for production builds.\r\n */\r\nexport function flightStrictPlugins(options?: {\r\n    env?: FlightEnvPluginOptions;\r\n    serverBoundary?: ServerBoundaryPluginOptions;\r\n}): Plugin[] {\r\n    return [\r\n        flightEnvPlugin({\r\n            privateVarBehavior: 'error',\r\n            ...options?.env,\r\n        }),\r\n        serverBoundaryPlugin({\r\n            violationBehavior: 'error',\r\n            ...options?.serverBoundary,\r\n        }),\r\n    ];\r\n}\r\n"]}

package/dist/plugins/server-boundary-plugin.d.ts

@@ -0,0 +1,67 @@
+import { Plugin } from 'vite';
+
+/**
+ * @flight-framework/core - Server Boundary Plugin
+ *
+ * Vite plugin to detect server-only code imported in client bundles.
+ * OPTIONAL - use if you want build-time protection.
+ *
+ * Features:
+ * - Detects *.server.ts files imported in client code
+ * - Detects /server/ and /api/ directory imports
+ * - Configurable behavior (warn, error)
+ * - Clear error messages with solutions
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { serverBoundaryPlugin } from '@flight-framework/core/plugins';
+ *
+ * export default {
+ *   plugins: [serverBoundaryPlugin()],
+ * };
+ * ```
+ */
+
+interface ServerBoundaryPluginOptions {
+    /**
+     * File patterns that are server-only.
+     * @default ['.server.ts', '.server.tsx', '.server.js', '.server.jsx']
+     */
+    serverFilePatterns?: string[];
+    /**
+     * Directory patterns that are server-only.
+     * @default ['/server/', '/api/']
+     */
+    serverDirPatterns?: string[];
+    /**
+     * How to handle violations.
+     * - 'error': Build error (recommended for production)
+     * - 'warn': Warning only (for migration)
+     * @default 'error'
+     */
+    violationBehavior?: 'error' | 'warn';
+    /**
+     * Custom error message template.
+     */
+    customErrorMessage?: (module: string, importer: string) => string;
+    /**
+     * Files to exclude from checking (e.g., tests).
+     * @default ['**\/*.test.*', '**\/*.spec.*']
+     */
+    exclude?: string[];
+}
+/**
+ * Vite plugin to detect server-only imports in client code.
+ *
+ * This plugin is OPTIONAL. Use it if you want build-time
+ * detection of server code leaking to the client.
+ *
+ * By default, it will:
+ * - Block imports of *.server.ts files in client code
+ * - Block imports from /server/ and /api/ directories
+ * - Throw build errors with clear solutions
+ */
+declare function serverBoundaryPlugin(options?: ServerBoundaryPluginOptions): Plugin;
+
+export { type ServerBoundaryPluginOptions, serverBoundaryPlugin };

package/dist/plugins/server-boundary-plugin.js

@@ -0,0 +1,3 @@
+export { serverBoundaryPlugin } from '../chunk-56ZZNOJD.js';
+//# sourceMappingURL=server-boundary-plugin.js.map
+//# sourceMappingURL=server-boundary-plugin.js.map

package/dist/plugins/server-boundary-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"server-boundary-plugin.js"}

package/dist/utils/index.d.ts

@@ -1,42 +1,97 @@
+export { g as getEnvironment, d as isBrowser, a as isDevelopment, i as isProduction, c as isServer, b as isTest } from '../env-9do2c6yn.js';
+
 /**
- * @flight-framework/core - Environment Utilities
+ * @flight-framework/core - Server/Client Boundaries
  *
- * Environment detection utilities that work across Node.js, browsers, and edge runtimes.
- * No hardcoded values - detects environment dynamically.
- */
-/**
- * Check if running in production environment.
+ * Runtime utilities for server/client code separation.
+ * These are OPTIONAL - use them if you want safety guards.
+ * Flight doesn't force you to use them.
  *
- * Detection order:
- * 1. Node.js process.env.NODE_ENV
- * 2. Vite/modern bundlers import.meta.env.MODE or import.meta.env.PROD
- * 3. Default: false (not production)
- */
-declare function isProduction(): boolean;
-/**
- * Check if running in development environment.
+ * @example
+ * ```typescript
+ * import { assertServer, getEnv } from '@flight-framework/core';
  *
- * Detection order:
- * 1. Node.js process.env.NODE_ENV
- * 2. Vite/modern bundlers import.meta.env.MODE or import.meta.env.DEV
- * 3. Default: true (assume development if unknown)
+ * export async function fetchFromDatabase() {
+ *   assertServer('fetchFromDatabase'); // Throws if called on client
+ *   const dbUrl = getEnv('DATABASE_URL'); // Returns undefined on client
+ *   // ... your code
+ * }
+ * ```
  */
-declare function isDevelopment(): boolean;
 /**
- * Check if running in test environment.
+ * Assert that code is running on the server.
+ * Throws an error if called from the client (browser).
+ *
+ * Use this to protect server-only code from being accidentally
+ * called on the client.
+ *
+ * @param context - Optional context string for the error message
+ * @throws Error if called on client
+ *
+ * @example
+ * ```typescript
+ * export async function queryDatabase() {
+ *   assertServer('queryDatabase');
+ *   // Safe to use process.env, database connections, etc.
+ * }
+ * ```
  */
-declare function isTest(): boolean;
+declare function assertServer(context?: string): void;
 /**
- * Check if running on the server (not browser).
+ * Assert that code is running on the client.
+ * Throws an error if called from the server.
+ *
+ * Use this to protect client-only code (e.g., DOM manipulation,
+ * browser APIs) from being accidentally called during SSR.
+ *
+ * @param context - Optional context string for the error message
+ * @throws Error if called on server
+ *
+ * @example
+ * ```typescript
+ * export function scrollToTop() {
+ *   assertClient('scrollToTop');
+ *   window.scrollTo(0, 0);
+ * }
+ * ```
  */
-declare function isServer(): boolean;
+declare function assertClient(context?: string): void;
 /**
- * Check if running in the browser.
+ * Get an environment variable safely.
+ *
+ * On the server: Returns the variable value.
+ * On the client: Returns undefined for non-public vars.
+ *
+ * Public variables (prefixed with FLIGHT_PUBLIC_) are always accessible.
+ *
+ * @param key - Environment variable name
+ * @returns The value or undefined
+ *
+ * @example
+ * ```typescript
+ * // On server: returns actual value
+ * // On client: returns undefined (safe!)
+ * const dbUrl = getEnv('DATABASE_URL');
+ *
+ * // Works on both server and client
+ * const apiUrl = getEnv('FLIGHT_PUBLIC_API_URL');
+ * ```
  */
-declare function isBrowser(): boolean;
+declare function getEnv(key: string): string | undefined;
 /**
- * Get the current environment name.
+ * Get an environment variable, throwing if not found.
+ * Use this when a variable is required.
+ *
+ * @param key - Environment variable name
+ * @returns The value
+ * @throws Error if variable is not set or inaccessible
+ *
+ * @example
+ * ```typescript
+ * // Throws if DATABASE_URL is not set
+ * const dbUrl = requireEnv('DATABASE_URL');
+ * ```
  */
-declare function getEnvironment(): 'production' | 'development' | 'test' | 'unknown';
+declare function requireEnv(key: string): string;
 
-export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest };
+export { assertClient, assertServer, getEnv, requireEnv };

package/dist/utils/index.js

@@ -1,4 +1,4 @@
-import '../chunk-PL37KFRJ.js';
+export { assertClient, assertServer, getEnv, requireEnv } from '../chunk-WF46NESN.js';
 export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest } from '../chunk-YHEVHRLH.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@flight-framework/core",
-  "version": "0.5.0",
-  "description": "Core primitives for Flight Framework - routing, rendering, caching",
+  "version": "0.6.1",
+  "description": "Core primitives for Flight Framework - routing, rendering, caching, server/client boundaries",
   "keywords": [
     "flight",
     "framework",
     "core",
     "ssr",
-    "routing"
+    "routing",
+    "server-components",
+    "boundaries"
   ],
   "license": "MIT",
   "author": "Flight Contributors",
@@ -182,6 +184,14 @@
     "./plugins/critical-css": {
       "types": "./dist/plugins/critical-css.d.ts",
       "import": "./dist/plugins/critical-css.js"
+    },
+    "./plugins/env": {
+      "types": "./dist/plugins/env-plugin.d.ts",
+      "import": "./dist/plugins/env-plugin.js"
+    },
+    "./plugins/server-boundary": {
+      "types": "./dist/plugins/server-boundary-plugin.d.ts",
+      "import": "./dist/plugins/server-boundary-plugin.js"
     }
   },
   "main": "./dist/index.js",