@useavalon/avalon 0.1.0

package/src/build/README.md

@@ -0,0 +1,310 @@
+# Avalon Build System
+
+This directory contains the build system components for Avalon, including integration detection, bundling, and optimization.
+
+## Components
+
+### Integration Detection (`integration-detection-plugin.ts`)
+
+Automatically detects which framework integrations are used in your project by:
+- Scanning file extensions (`.vue`, `.svelte`)
+- Analyzing imports in TSX/JSX files
+- Detecting framework-specific patterns
+
+**Usage:**
+```typescript
+import { detectUsedIntegrations, getRequiredIntegrations } from './integration-detection-plugin.ts';
+
+const detected = await detectUsedIntegrations();
+const required = getRequiredIntegrations(detected);
+// required = ['preact', 'vue', 'solid', 'svelte']
+```
+
+### Integration Resolver (`integration-resolver-plugin.ts`)
+
+Resolves `@useavalon/integration-*` imports to actual file paths:
+
+```typescript
+// Import resolution
+'@useavalon/integration-preact' → 'src/integrations/preact/mod.ts'
+'@useavalon/integration-preact/server' → 'src/integrations/preact/server/renderer.ts'
+'@useavalon/integration-preact/client' → 'src/integrations/preact/client/index.ts'
+```
+
+**Usage:**
+```typescript
+import { integrationResolverPlugin, createIntegrationAliases } from './integration-resolver-plugin.ts';
+
+// In Vite config
+plugins: [
+  integrationResolverPlugin(),
+]
+
+// Or use aliases
+resolve: {
+  alias: createIntegrationAliases(),
+}
+```
+
+### Integration Bundler (`integration-bundler-plugin.ts`)
+
+Handles bundling of integration packages for both client and SSR builds:
+
+**Usage:**
+```typescript
+import { integrationBundlerPlugin } from './integration-bundler-plugin.ts';
+
+// Client build
+plugins: [
+  integrationBundlerPlugin({ 
+    integrations: ['preact', 'vue'], 
+    ssr: false 
+  }),
+]
+
+// SSR build
+plugins: [
+  integrationBundlerPlugin({ 
+    integrations: ['preact', 'vue'], 
+    ssr: true 
+  }),
+]
+```
+
+### Integration Config (`integration-config.ts`)
+
+Centralized configuration for all framework integrations:
+
+```typescript
+export interface IntegrationBuildConfig {
+  name: string;
+  extensions: string[];
+  optimizeDeps: string[];
+  ssrExternal: string[];
+  ssrNoExternal: string[];
+  requiresPlugin: boolean;
+  pluginPackage?: string;
+}
+```
+
+**Usage:**
+```typescript
+import { 
+  getIntegrationBuildConfig,
+  getOptimizeDepsForIntegrations,
+  getSSRNoExternalForIntegrations 
+} from './integration-config.ts';
+
+const config = getIntegrationBuildConfig('preact');
+const optimizeDeps = getOptimizeDepsForIntegrations(['preact', 'vue']);
+const ssrNoExternal = getSSRNoExternalForIntegrations(['preact', 'vue']);
+```
+
+### Island Manifest (`island-manifest.ts`)
+
+Generates a manifest of all islands with their framework types and bundle paths:
+
+```typescript
+export interface IslandManifest {
+  islands: Record<string, IslandEntry>;
+  version: string;
+  buildTime: number;
+}
+
+export interface IslandEntry {
+  src: string;
+  bundle: string;
+  hash: string;
+  framework: 'preact' | 'solid' | 'vue' | 'svelte' | 'vanilla';
+  deps: string[];
+}
+```
+
+**Usage:**
+```typescript
+import { generateIslandManifest, loadIslandManifest } from './island-manifest.ts';
+
+// During build
+const manifest = await generateIslandManifest();
+await Deno.writeTextFile('dist/island-manifest.json', JSON.stringify(manifest));
+
+// At runtime
+const manifest = await loadIslandManifest();
+const bundlePath = getIslandBundlePath('/islands/Counter.tsx', manifest);
+```
+
+### MDX Plugin (`mdx-plugin.ts`)
+
+Handles MDX file processing with support for framework components.
+
+## Build Configurations
+
+### Main Build (`vite.config.ts`)
+
+Client-side build configuration:
+- Detects used integrations
+- Bundles client hydration code
+- Optimizes dependencies
+- Includes island bundles
+
+### SSR Build (`vite.ssr.config.ts`)
+
+Server-side rendering build configuration:
+- Bundles SSR rendering code
+- Includes island SSR bundles
+- Configures SSR externals
+- Outputs to `dist/ssr/`
+
+## Build Process
+
+The build process is orchestrated by `build.ts`:
+
+1. **Integration Detection**: Scan project to detect frameworks
+2. **Manifest Generation**: Create island manifest
+3. **Client Build**: Bundle client code with Vite
+4. **SSR Build**: Bundle SSR code with Vite SSR config
+
+```bash
+deno run --allow-all build.ts
+```
+
+## Tree Shaking
+
+The build system automatically tree-shakes unused integrations:
+
+- Only detected integrations are bundled
+- Framework dependencies are excluded if not used
+- Vite plugins are only loaded for used frameworks
+
+**Example:**
+```
+Project uses: Preact, Vue
+Build includes: preact integration, vue integration
+Build excludes: solid integration, svelte integration
+```
+
+## Testing
+
+Test integration detection:
+```bash
+deno run --allow-read test-integration-detection.ts
+```
+
+Expected output:
+```
+🔍 Testing integration detection...
+
+Detected integrations:
+  Preact: ✅
+  Vue: ✅
+  Solid: ✅
+  Svelte: ✅
+
+Required integrations: preact, vue, solid, svelte
+
+✅ Integration detection test complete!
+```
+
+## Adding a New Integration
+
+To add support for a new framework:
+
+1. **Create Integration Package**
+   ```
+   src/integrations/[framework]/
+   ├── mod.ts
+   ├── server/
+   │   └── renderer.ts
+   ├── client/
+   │   └── index.ts
+   └── types.ts
+   ```
+
+2. **Add Build Configuration**
+   ```typescript
+   // In integration-config.ts
+   export const INTEGRATION_BUILD_CONFIGS = {
+     // ...
+     myframework: {
+       name: 'myframework',
+       extensions: ['.myext'],
+       optimizeDeps: ['myframework'],
+       ssrExternal: [],
+       ssrNoExternal: ['myframework'],
+       requiresPlugin: true,
+       pluginPackage: 'vite-plugin-myframework',
+     },
+   };
+   ```
+
+3. **Update Detection Logic**
+   ```typescript
+   // In integration-detection-plugin.ts
+   export async function detectUsedIntegrations() {
+     const result = {
+       // ...
+       myframework: false,
+     };
+     
+     // Add detection logic
+     if (entry.name.endsWith('.myext')) {
+       result.myframework = true;
+     }
+     
+     return result;
+   }
+   ```
+
+4. **Add Resolver Aliases**
+   ```typescript
+   // In integration-resolver-plugin.ts
+   export function createIntegrationAliases() {
+     return {
+       // ...
+       '@useavalon/integration-myframework': resolve(cwd, 'src/integrations/myframework/mod.ts'),
+     };
+   }
+   ```
+
+## Performance
+
+### Build Time Impact
+
+- Integration detection: ~10-50ms
+- Plugin initialization: ~5-20ms per integration
+- Total overhead: <100ms for typical projects
+
+### Bundle Size Impact
+
+Per-integration overhead (gzipped):
+- Preact: ~4KB (client) + ~8KB (server)
+- Vue: ~10KB (client) + ~15KB (server)
+- Solid: ~7KB (client) + ~10KB (server)
+- Svelte: ~5KB (client) + ~12KB (server)
+
+## Troubleshooting
+
+### Integration Not Detected
+
+Check:
+1. File extensions match integration config
+2. Files are in scanned directories
+3. Imports use correct framework packages
+
+### Build Errors
+
+Common issues:
+- Missing Vite plugin: Install required plugin
+- Module resolution: Check integration aliases
+- SSR errors: Verify SSR noExternal config
+
+### Bundle Size
+
+To optimize:
+1. Remove unused framework imports
+2. Verify tree-shaking is working
+3. Check that only used integrations are bundled
+
+## Documentation
+
+See [docs/build-system-integrations.md](../../docs/build-system-integrations.md) for detailed documentation.

package/src/build/integration-bundler-plugin.ts

@@ -0,0 +1,116 @@
+import type { Plugin } from 'vite';
+import { resolve } from 'node:path';
+import { getOptimizeDepsForIntegrations, getSSRNoExternalForIntegrations } from './integration-config.ts';
+
+export interface IntegrationBundlerOptions {
+	/** Integrations to include in the build */
+	integrations: string[];
+	/** Whether to bundle for SSR */
+	ssr?: boolean;
+}
+
+/**
+ * Vite plugin to bundle integration packages
+ * Ensures integration server and client code is properly bundled
+ */
+export function integrationBundlerPlugin(options: IntegrationBundlerOptions): Plugin {
+	const { integrations, ssr = false } = options;
+	const cwd = process.cwd();
+
+	return {
+		name: 'avalon:integration-bundler',
+		enforce: 'post',
+
+		config(config) {
+			// Add integration entry points to the build
+			const entries: Record<string, string> = {};
+			
+			for (const framework of integrations) {
+				if (ssr) {
+					// SSR build: include server-side integration code
+					entries[`integrations/${framework}/server`] = resolve(
+						cwd,
+						`packages/integrations/${framework}/server/renderer.ts`
+					);
+				} else {
+					// Client build: include client-side integration code
+					entries[`integrations/${framework}/client`] = resolve(
+						cwd,
+						`packages/integrations/${framework}/client/index.ts`
+					);
+				}
+			}
+
+			// Merge with existing rolldown input
+			const existingInput = config.build?.rolldownOptions?.input || {};
+			const mergedInput = typeof existingInput === 'string' 
+				? { main: existingInput, ...entries }
+				: { ...existingInput, ...entries };
+
+			return {
+				build: {
+					rolldownOptions: {
+						input: mergedInput,
+					},
+				},
+			};
+		},
+
+
+	};
+}
+
+/**
+ * Get external dependencies for integration bundling
+ * These should not be bundled but loaded from node_modules
+ */
+export function getIntegrationExternals(framework: string, ssr: boolean) {
+	const externals: string[] = [];
+
+	// Framework-specific externals
+	switch (framework) {
+		case 'preact':
+			if (!ssr) {
+				// Client-side: preact should be bundled for hydration
+				return [];
+			}
+			// SSR: keep preact external if needed
+			externals.push('preact', 'preact/hooks', 'preact-render-to-string');
+			break;
+
+		case 'vue':
+			if (ssr) {
+				// SSR: Vue server renderer should be external
+				externals.push('vue', 'vue/server-renderer', '@vue/server-renderer', '@vue/shared');
+			}
+			break;
+
+		case 'solid':
+			if (ssr) {
+				externals.push('solid-js', 'solid-js/web');
+			}
+			break;
+
+		case 'svelte':
+			if (ssr) {
+				externals.push('svelte', 'svelte/server', 'svelte/compiler', 'svelte/internal');
+			}
+			break;
+	}
+
+	return externals;
+}
+
+/**
+ * Configure optimization for integration dependencies
+ */
+export function getIntegrationOptimizeDeps(integrations: string[]) {
+	return getOptimizeDepsForIntegrations(integrations);
+}
+
+/**
+ * Get SSR noExternal packages for integrations
+ */
+export function getIntegrationSSRNoExternal(integrations: string[]) {
+	return getSSRNoExternalForIntegrations(integrations);
+}

package/src/build/integration-config.ts

@@ -0,0 +1,168 @@
+/**
+ * Integration configuration for build system
+ * Defines how each integration should be bundled and optimized
+ */
+
+export interface IntegrationBuildConfig {
+	/** Framework name */
+	name: string;
+	/** File extensions this integration handles */
+	extensions: string[];
+	/** NPM packages that should be optimized for this integration */
+	optimizeDeps: string[];
+	/** NPM packages that should be external in SSR builds */
+	ssrExternal: string[];
+	/** NPM packages that should NOT be external in SSR builds */
+	ssrNoExternal: string[];
+	/** Whether this integration requires a Vite plugin */
+	requiresPlugin: boolean;
+	/** Plugin package name (if requiresPlugin is true) */
+	pluginPackage?: string;
+}
+
+/**
+ * Build configuration for all supported integrations
+ */
+export const INTEGRATION_BUILD_CONFIGS: Record<string, IntegrationBuildConfig> = {
+	preact: {
+		name: 'preact',
+		extensions: ['.tsx', '.jsx'],
+		optimizeDeps: [
+			'preact',
+			'preact/hooks',
+			'preact/jsx-runtime',
+			'preact/jsx-dev-runtime',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['preact', 'preact-render-to-string'],
+		requiresPlugin: false,
+	},
+
+	vue: {
+		name: 'vue',
+		extensions: ['.vue'],
+		optimizeDeps: ['vue'],
+		ssrExternal: [],
+		ssrNoExternal: ['vue', '@vue/server-renderer', '@vue/shared'],
+		requiresPlugin: true,
+		pluginPackage: '@vitejs/plugin-vue',
+	},
+
+	solid: {
+		name: 'solid',
+		extensions: ['.tsx', '.jsx'],
+		optimizeDeps: [
+			'solid-js',
+			'solid-js/web',
+			'solid-js/store',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['solid-js', 'solid-js/web', 'solid-js/store'],
+		requiresPlugin: true,
+		pluginPackage: 'vite-plugin-solid',
+	},
+
+	svelte: {
+		name: 'svelte',
+		extensions: ['.svelte'],
+		optimizeDeps: [
+			'svelte',
+			'svelte/internal',
+			'svelte/store',
+			'svelte/animate',
+			'svelte/easing',
+			'svelte/motion',
+			'svelte/transition',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['svelte', 'svelte/server', 'svelte/internal', 'svelte/store'],
+		requiresPlugin: true,
+		pluginPackage: '@sveltejs/vite-plugin-svelte',
+	},
+
+	react: {
+		name: 'react',
+		extensions: ['.jsx', '.tsx'],
+		optimizeDeps: [
+			'react',
+			'react/jsx-runtime',
+			'react/jsx-dev-runtime',
+			'react-dom',
+			'react-dom/client',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['react', 'react-dom', 'react-dom/server'],
+		requiresPlugin: true,
+		pluginPackage: '@vitejs/plugin-react',
+	},
+
+	lit: {
+		name: 'lit',
+		extensions: ['.ts', '.js'],
+		optimizeDeps: [
+			'lit',
+			'lit/decorators.js',
+			'lit/directives/class-map.js',
+			'lit/directives/style-map.js',
+			'@lit/reactive-element',
+		],
+		ssrExternal: [],
+		ssrNoExternal: ['lit', '@lit-labs/ssr', '@lit/reactive-element', 'lit-html'],
+		requiresPlugin: false,
+	},
+};
+
+/**
+ * Get build configuration for a specific integration
+ */
+export function getIntegrationBuildConfig(framework: string) {
+	return INTEGRATION_BUILD_CONFIGS[framework];
+}
+
+/**
+ * Get all optimize deps for given integrations
+ */
+export function getOptimizeDepsForIntegrations(integrations: string[]) {
+	const deps = new Set<string>();
+	
+	for (const integration of integrations) {
+		const config = INTEGRATION_BUILD_CONFIGS[integration];
+		if (config) {
+			config.optimizeDeps.forEach(dep => deps.add(dep));
+		}
+	}
+	
+	return Array.from(deps);
+}
+
+/**
+ * Get SSR noExternal packages for given integrations
+ */
+export function getSSRNoExternalForIntegrations(integrations: string[]) {
+	const packages = new Set<string>();
+	
+	for (const integration of integrations) {
+		const config = INTEGRATION_BUILD_CONFIGS[integration];
+		if (config) {
+			config.ssrNoExternal.forEach(pkg => packages.add(pkg));
+		}
+	}
+	
+	return Array.from(packages);
+}
+
+/**
+ * Check if an integration requires a Vite plugin
+ */
+export function integrationRequiresPlugin(framework: string) {
+	const config = INTEGRATION_BUILD_CONFIGS[framework];
+	return config?.requiresPlugin ?? false;
+}
+
+/**
+ * Get plugin package name for an integration
+ */
+export function getIntegrationPluginPackage(framework: string) {
+	const config = INTEGRATION_BUILD_CONFIGS[framework];
+	return config?.pluginPackage;
+}

package/src/build/integration-detection-plugin.ts

@@ -0,0 +1,117 @@
+import type { Plugin } from 'vite';
+import { resolve } from 'node:path';
+import { readdir, readFile } from 'node:fs/promises';
+
+export interface IntegrationDetectionResult {
+	preact: boolean;
+	vue: boolean;
+	solid: boolean;
+	svelte: boolean;
+}
+
+/**
+ * Vite plugin to detect which framework integrations are used in the project
+ * This enables tree-shaking of unused integrations
+ */
+export function integrationDetectionPlugin(): Plugin {
+	let detectedIntegrations: IntegrationDetectionResult | null = null;
+
+	return {
+		name: 'avalon:integration-detection',
+		enforce: 'pre',
+
+		async buildStart() {
+			// Detect integrations during build start
+			detectedIntegrations = await detectUsedIntegrations();
+		},
+
+		resolveId(id: string) {
+			// Handle integration imports
+			if (id.startsWith('@useavalon/integration-')) {
+				const framework = id.replace('@useavalon/integration-', '').split('/')[0];
+				
+				// Check if this integration is used
+				if (detectedIntegrations && !detectedIntegrations[framework as keyof IntegrationDetectionResult]) {
+					console.warn(`⚠️ Integration ${framework} is imported but not detected in project files`);
+				}
+				
+				// Resolve to the actual integration path
+				const integrationPath = resolve(process.cwd(), `packages/integrations/${framework}/mod.ts`);
+				return integrationPath;
+			}
+			
+			return null;
+		},
+
+		transform(_code: string, id: string) {
+			// Track integration usage in island files
+			if (id.includes('/islands/') || id.includes('/components/')) {
+				// This helps with dynamic detection during development
+				return null;
+			}
+			
+			return null;
+		},
+	};
+}
+
+/**
+ * Detect which framework integrations are actually used in the project
+ */
+export async function detectUsedIntegrations() {
+	const result: IntegrationDetectionResult = {
+		preact: false,
+		vue: false,
+		solid: false,
+		svelte: false,
+	};
+
+	const searchDirs = ['islands', 'components', 'src/islands', 'src/components'];
+	const cwd = process.cwd();
+
+	for (const dir of searchDirs) {
+		try {
+			const dirPath = resolve(cwd, dir);
+			const entries = await readdir(dirPath, { withFileTypes: true });
+			for (const entry of entries) {
+				if (!entry.isFile()) continue;
+
+				// Check file extensions
+				if (entry.name.endsWith('.vue')) {
+					result.vue = true;
+				} else if (entry.name.endsWith('.svelte')) {
+					result.svelte = true;
+				} else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.jsx')) {
+					// Read file content to detect framework
+					const filePath = resolve(dirPath, entry.name);
+					const content = await readFile(filePath, 'utf-8');
+					
+					if (content.includes('solid-js')) {
+						result.solid = true;
+					} else {
+						// Default to Preact for JSX/TSX files
+						result.preact = true;
+					}
+				}
+			}
+		} catch {
+			// Directory doesn't exist, continue
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Get list of integration packages that should be included in the build
+ */
+export function getRequiredIntegrations(detected: IntegrationDetectionResult) {
+	const integrations: string[] = [];
+	
+	if (detected.preact) integrations.push('preact');
+	if (detected.vue) integrations.push('vue');
+	if (detected.solid) integrations.push('solid');
+	if (detected.svelte) integrations.push('svelte');
+	
+	return integrations;
+}