@flight-framework/bundler-flightpack 0.1.3 → 0.1.4

package/README.md

@@ -4,19 +4,21 @@ FlightPack native Rust bundler adapter for Flight Framework.
 
 ## Overview
 
-This package provides the TypeScript adapter that integrates FlightPack with the Flight Framework bundler interface. It wraps the native NAPI bindings to provide a seamless developer experience matching other Flight bundler adapters.
+This package provides the TypeScript adapter that integrates FlightPack with the Flight Framework bundler interface. It wraps the native NAPI bindings to provide a seamless developer experience with maximum performance.
 
 ## Features
 
 - **Native Performance** - 1,874+ files/second processing speed
 - **100% Rust Core** - No JavaScript runtime overhead in hot paths
 - **Zero Configuration** - Works out of the box with TypeScript/TSX
-- **HMR Support** - Native Axum WebSocket-based Hot Module Replacement
-- **RSC Ready** - React Server Components with directive detection
+- **Statement-Level Tree Shaking** - InnerGraph analysis for superior DCE
+- **Persistent Build Cache** - TurboCache + ArtifactStore for incremental builds
+- **Code Splitting** - ChunkSplitter with vendor/common chunk optimization
+- **Platform-Aware Builds** - Automatic externals for browser/node/edge
+- **React Server Components** - First-class RSC directive detection and manifests
 - **CSS Processing** - Lightning CSS for modules, minification, autoprefixer
-- **Universal Builds** - SSR, SSG, CSR, SPA, Edge deployment support
-- **Tree Shaking** - Dead code elimination
-- **Code Splitting** - Automatic chunk optimization
+- **Module Federation** - Rspack-compatible micro-frontend support
+- **HMR Support** - Native Axum WebSocket-based Hot Module Replacement
 
 ## Installation
 
@@ -38,133 +40,189 @@ export default defineConfig({
 });
 ```
 
-### With Options
+### With Full Options
 
 ```typescript
 import { flightpack } from '@flight-framework/bundler-flightpack';
 
 export default defineConfig({
     bundler: flightpack({
+        // Core Options
         minify: true,
         sourcemap: true,
         target: 'es2022',
-        rsc: true,
+        
+        // Tree Shaking (InnerGraph - statement level)
         treeshake: true,
+        
+        // Code Splitting (ChunkSplitter)
         splitting: true,
+        chunkSizeLimit: 500,
+        
+        // Persistent Caching
+        cache: true,
+        cacheDir: '.flightpack_cache',
+        
+        // React Server Components
+        rsc: true,
+        
+        // Platform & Externals
+        platform: 'browser', // 'browser' | 'node' | 'edge' | 'neutral'
+        external: [],
+        noExternal: [],
+        
+        // Module Federation
+        federation: {
+            name: 'app',
+            filename: 'remoteEntry.js',
+            exposes: {
+                './Button': './src/components/Button.tsx',
+            },
+            shared: {
+                react: { singleton: true },
+            },
+        },
+        
+        // Development
+        hmr: true,
     }),
 });
 ```
 
-## Configuration Options
+## Build Process
+
+The adapter implements a comprehensive 6-phase production build:
+
+```
+Phase 1/6: Client Build (Browser Platform)
+Phase 2/6: Server Build (Node Platform, SSR)
+Phase 3/6: Edge Build (Edge Platform, optional)
+Phase 4/6: CSS Processing (Lightning CSS)
+Phase 5/6: Static Assets (HTML injection, public files)
+Phase 6/6: RSC Manifests (client/server references)
+```
+
+### Build Output Structure
+
+```
+dist/
+  client/
+    assets/
+      main.js          - Client bundle
+      global.css       - Processed CSS
+    index.html         - HTML with injected scripts
+    react-client-manifest.json
+  server/
+    main.js            - SSR bundle
+    react-server-manifest.json
+  edge/                - Optional edge bundle
+.flightpack_cache/     - Persistent cache (content-addressed)
+```
+
+## Configuration Reference
+
+### Core Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `minify` | `boolean` | `true` | Enable minification in production |
-| `sourcemap` | `boolean \| 'inline'` | `true` | Generate source maps |
+| `sourcemap` | `boolean \| 'inline' \| 'hidden'` | `true` | Generate source maps |
 | `target` | `string` | `'es2022'` | JavaScript target environment |
-| `treeshake` | `boolean` | `true` | Enable tree shaking |
-| `rsc` | `boolean` | `true` | Enable RSC directive detection |
-| `hmr` | `boolean` | `true` | Enable HMR in development |
-| `splitting` | `boolean` | `true` | Enable code splitting |
+
+### Tree Shaking
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `treeshake` | `boolean \| TreeShakeConfig` | `true` | Enable InnerGraph tree shaking |
+| `treeshake.innerGraph` | `boolean` | `true` | Statement-level dead code elimination |
+| `treeshake.preserve` | `string[]` | `[]` | Modules to exclude from tree shaking |
+
+### Code Splitting
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `splitting` | `boolean \| SplittingConfig` | `true` | Enable code splitting |
+| `splitting.minSize` | `number` | - | Minimum shared chunk size in bytes |
+| `splitting.maxSize` | `number` | - | Maximum chunk size before warning |
+| `splitting.vendorChunk` | `boolean` | `true` | Extract vendor dependencies |
 | `chunkSizeLimit` | `number` | `500` | Warn on chunks larger than (KB) |
 
-## Bundler Interface
+### Caching
 
-The adapter implements the full `BundlerAdapter` interface:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cache` | `boolean \| CacheConfig` | `true` | Enable incremental build cache |
+| `cacheDir` | `string` | `.flightpack_cache` | Persistent cache directory |
+| `cache.maxSize` | `number` | - | Maximum cache size in MB |
 
-```typescript
-interface BundlerAdapter {
-    name: string;
-    
-    // Build operations
-    build(config: FlightConfig): Promise<BuildResult>;
-    transform(code: string, id: string, config: FlightConfig): Promise<TransformResult | null>;
-    
-    // Development server
-    createDevServer(config: FlightConfig): Promise<DevServer>;
-    
-    // Module resolution
-    resolve(id: string, importer: string | undefined, config: FlightConfig): Promise<string | null>;
-}
-```
+### Platform & Externals
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `platform` | `'browser' \| 'node' \| 'edge' \| 'neutral'` | `'browser'` | Target platform |
+| `external` | `string[]` | `[]` | Packages to externalize |
+| `noExternal` | `string[]` | `[]` | Force bundle (override auto-external) |
+
+### React Server Components
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rsc` | `boolean` | `true` | Enable RSC directive detection |
 
 ## Development Server
 
 The dev server uses native Rust (Axum) for maximum performance:
 
 ```typescript
-const adapter = await flightpack();
+const adapter = flightpack();
 const devServer = await adapter.createDevServer(config);
 
-// Server runs on native Axum with WebSocket HMR
-await devServer.listen(3000);
-
-// File watcher triggers HMR updates
-devServer.on('update', (modules) => {
-    console.log('Updated:', modules);
-});
+// Server with WebSocket HMR
+console.log(devServer.url);  // http://localhost:5173
 
 // Graceful shutdown
 await devServer.close();
 ```
 
-## CSS Handling
+## CSS Processing
 
-The adapter provides native CSS processing:
+The adapter provides native Lightning CSS processing:
 
-- **CSS Minification** - Lightning CSS for fast minification
-- **CSS Modules** - Class name hashing with exports
-- **Autoprefixer** - Automatic vendor prefixes
-- **Source Maps** - Development debugging support
+- CSS Minification with optimal compression
+- CSS Modules with class name hashing
+- Autoprefixer with configurable browser targets
+- Source Maps for development debugging
 
 ```typescript
-// .css files are minified and injected
+// Standard CSS - minified and bundled
 import './styles.css';
 
-// .module.css files export class mappings
+// CSS Modules - exports class mappings
 import styles from './component.module.css';
 console.log(styles.button); // 'button_a1b2c3'
 ```
 
-## Universal Platform Support
-
-The adapter includes utilities for multi-platform builds:
-
-```typescript
-import { flightpack } from '@flight-framework/bundler-flightpack';
+## Platform Support
 
-// Access native externals detection
-const native = await loadNativeBinding();
+The adapter automatically handles platform-specific externals:
 
-// SSR - detect Node.js builtins to externalize
-native.isNodeBuiltin('fs');     // true
-native.isBareImport('express'); // true
+| Platform | Auto-External | Resolve Conditions |
+|----------|---------------|-------------------|
+| Browser | None | `browser`, `import`, `module` |
+| Node | Node.js builtins | `node`, `import`, `module` |
+| Edge | Edge-incompatible modules | `edge`, `worker`, `import`, `module` |
+| Neutral | None | `import`, `module` |
 
-// Edge - check runtime compatibility
-native.isEdgeCompatible('crypto'); // true
-native.isEdgeCompatible('fs');     // false
-
-// Platform-specific resolve conditions
-native.getPlatformConditions('browser'); // ['browser', 'import', 'module']
-native.getPlatformConditions('node');    // ['node', 'import', 'module']
-native.getPlatformConditions('edge');    // ['edge', 'worker', 'import', 'module']
-```
-
-## Performance
-
-FlightPack benchmarks against Flight Framework monorepo:
+## Performance Benchmarks
 
 ```
 Files Processed:    126
 Total Lines:     36,231
-
-Total Time:         67 ms
+Total Time:         66 ms
 Files/second:    1,874
 Lines/second:  538,908
 ```
 
-### Comparison
-
 | Bundler | Files/sec | Category |
 |---------|-----------|----------|
 | FlightPack | 1,874 | Elite |
@@ -175,7 +233,7 @@ Lines/second:  538,908
 
 ## Native Bindings
 
-This adapter wraps the `@flight-framework/flightpack` NAPI package which provides 21 native functions:
+This adapter wraps `@flight-framework/flightpack` which provides 21 native NAPI functions:
 
 | Category | Functions |
 |----------|-----------|
@@ -183,7 +241,7 @@ This adapter wraps the `@flight-framework/flightpack` NAPI package which provide
 | Dev Server | `startDevServer`, `stopDevServer`, `isDevServerRunning` |
 | HMR | `sendHmrUpdate`, `sendHmrError`, `watchFiles`, `WatchHandle` |
 | CSS | `transformCss`, `minifyCss`, `transformCssModule` |
-| Universal | `isNodeBuiltin`, `getNodeBuiltins`, `isBareImport`, `isEdgeCompatible`, `getPlatformConditions` |
+| Platform | `isNodeBuiltin`, `getNodeBuiltins`, `isBareImport`, `isEdgeCompatible`, `getPlatformConditions` |
 
 ## Related Packages
 
@@ -192,7 +250,6 @@ This adapter wraps the `@flight-framework/flightpack` NAPI package which provide
 | `@flight-framework/flightpack` | Native NAPI bindings |
 | `@flight-framework/bundler` | Bundler interface definitions |
 | `@flight-framework/bundler-vite` | Vite adapter alternative |
-| `@flight-framework/bundler-esbuild` | esbuild adapter alternative |
 
 ## License