@flight-framework/bundler-flightpack 0.1.4 → 0.1.6

package/README.md

@@ -4,21 +4,19 @@ 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 with maximum performance.
+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.
 
 ## 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
-- **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
-- **Module Federation** - Rspack-compatible micro-frontend support
 - **HMR Support** - Native Axum WebSocket-based Hot Module Replacement
+- **RSC Ready** - React Server Components with directive detection
+- **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
 
 ## Installation
 
@@ -40,189 +38,133 @@ export default defineConfig({
 });
 ```
 
-### With Full Options
+### With Options
 
 ```typescript
 import { flightpack } from '@flight-framework/bundler-flightpack';
 
 export default defineConfig({
     bundler: flightpack({
-        // Core Options
         minify: true,
         sourcemap: true,
         target: 'es2022',
-        
-        // Tree Shaking (InnerGraph - statement level)
+        rsc: true,
         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,
     }),
 });
 ```
 
-## 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
+## Configuration Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `minify` | `boolean` | `true` | Enable minification in production |
-| `sourcemap` | `boolean \| 'inline' \| 'hidden'` | `true` | Generate source maps |
+| `sourcemap` | `boolean \| 'inline'` | `true` | Generate source maps |
 | `target` | `string` | `'es2022'` | JavaScript target environment |
-
-### 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 |
+| `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 |
 | `chunkSizeLimit` | `number` | `500` | Warn on chunks larger than (KB) |
 
-### Caching
+## Bundler 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 |
-
-### 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
+The adapter implements the full `BundlerAdapter` interface:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `rsc` | `boolean` | `true` | Enable RSC directive detection |
+```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>;
+}
+```
 
 ## Development Server
 
 The dev server uses native Rust (Axum) for maximum performance:
 
 ```typescript
-const adapter = flightpack();
+const adapter = await flightpack();
 const devServer = await adapter.createDevServer(config);
 
-// Server with WebSocket HMR
-console.log(devServer.url);  // http://localhost:5173
+// 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);
+});
 
 // Graceful shutdown
 await devServer.close();
 ```
 
-## CSS Processing
+## CSS Handling
 
-The adapter provides native Lightning CSS processing:
+The adapter provides native CSS processing:
 
-- CSS Minification with optimal compression
-- CSS Modules with class name hashing
-- Autoprefixer with configurable browser targets
-- Source Maps for development debugging
+- **CSS Minification** - Lightning CSS for fast minification
+- **CSS Modules** - Class name hashing with exports
+- **Autoprefixer** - Automatic vendor prefixes
+- **Source Maps** - Development debugging support
 
 ```typescript
-// Standard CSS - minified and bundled
+// .css files are minified and injected
 import './styles.css';
 
-// CSS Modules - exports class mappings
+// .module.css files export class mappings
 import styles from './component.module.css';
 console.log(styles.button); // 'button_a1b2c3'
 ```
 
-## Platform Support
+## Universal Platform Support
+
+The adapter includes utilities for multi-platform builds:
+
+```typescript
+import { flightpack } from '@flight-framework/bundler-flightpack';
 
-The adapter automatically handles platform-specific externals:
+// Access native externals detection
+const native = await loadNativeBinding();
 
-| 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` |
+// SSR - detect Node.js builtins to externalize
+native.isNodeBuiltin('fs');     // true
+native.isBareImport('express'); // true
 
-## Performance Benchmarks
+// 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:
 
 ```
 Files Processed:    126
 Total Lines:     36,231
-Total Time:         66 ms
+
+Total Time:         67 ms
 Files/second:    1,874
 Lines/second:  538,908
 ```
 
+### Comparison
+
 | Bundler | Files/sec | Category |
 |---------|-----------|----------|
 | FlightPack | 1,874 | Elite |
@@ -233,7 +175,7 @@ Lines/second:  538,908
 
 ## Native Bindings
 
-This adapter wraps `@flight-framework/flightpack` which provides 21 native NAPI functions:
+This adapter wraps the `@flight-framework/flightpack` NAPI package which provides 21 native functions:
 
 | Category | Functions |
 |----------|-----------|
@@ -241,7 +183,7 @@ This adapter wraps `@flight-framework/flightpack` which provides 21 native NAPI
 | Dev Server | `startDevServer`, `stopDevServer`, `isDevServerRunning` |
 | HMR | `sendHmrUpdate`, `sendHmrError`, `watchFiles`, `WatchHandle` |
 | CSS | `transformCss`, `minifyCss`, `transformCssModule` |
-| Platform | `isNodeBuiltin`, `getNodeBuiltins`, `isBareImport`, `isEdgeCompatible`, `getPlatformConditions` |
+| Universal | `isNodeBuiltin`, `getNodeBuiltins`, `isBareImport`, `isEdgeCompatible`, `getPlatformConditions` |
 
 ## Related Packages
 
@@ -250,6 +192,7 @@ This adapter wraps `@flight-framework/flightpack` which provides 21 native NAPI
 | `@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