feat(docs): add tree-shaking analysis for @codefast/ui package

Added a detailed analysis to the documentation addressing tree-shaking effectiveness for the `@codefast/ui` package. The document outlines current limitations, optimization recommendations, and expected impact on bundle size and import efficiency, prioritizing backward compatibility while improving selective import usage.

Author: thevuong

docs/tree-shaking-analysis.md

@@ -0,0 +1,167 @@
+# Tree-shaking Analysis for @codefast/ui Package
+
+## Current State Analysis
+
+### ✅ Positive Aspects for Tree-shaking
+
+1. **Package Configuration**:
+   - `"sideEffects": false` - Correctly configured
+   - `"type": "module"` - Uses ES modules
+   - Proper `exports` field with ESM/CJS support
+   - `bundle: false` in rslib.config.ts - Preserves modular structure
+
+2. **Build Output**:
+   - Individual component files are preserved (1-20KB each)
+   - Modular directory structure maintained in dist/
+   - Both ESM and CJS formats generated
+
+### ❌ Tree-shaking Issues Identified
+
+1. **Three-Level Barrel Export Chain**:
+   ```
+   src/index.ts (572 lines)
+   ↓ imports from @/components
+   src/components/index.ts (616 lines)
+   ↓ imports from individual components
+   component/index.ts
+   ↓ imports from actual component files
+   ```
+
+2. **Main Entry Point Problems**:
+   - `dist/esm/index.js`: 11KB minified single line with all imports
+   - `dist/esm/components/index.js`: 14KB barrel export
+   - Single entry point in package.json exports field
+
+3. **Bundle Size Impact**:
+   - Total package size: 488.2KB
+   - Main index files create large import graphs
+   - Importing single component may pull in references to all components
+
+## Tree-shaking Effectiveness Test
+
+When importing `import { Button } from '@codefast/ui'`:
+- Bundler must process the entire 11KB index.js file
+- File contains references to all ~60+ components
+- Even with tree-shaking, the import graph is unnecessarily large
+
+## Recommendations for Improvement
+
+### 1. **Individual Component Exports** (Recommended)
+Add individual component exports to package.json:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./button": {
+      "import": "./dist/esm/components/button/index.js",
+      "require": "./dist/cjs/components/button/index.cjs"
+    },
+    "./accordion": {
+      "import": "./dist/esm/components/accordion/index.js",
+      "require": "./dist/cjs/components/accordion/index.cjs"
+    },
+    "./styles.css": "./dist/styles/index.css"
+  }
+}
+```
+
+### 2. **Remove Barrel Export Layers**
+- Keep individual component index.ts files
+- Remove or minimize src/components/index.ts
+- Consider making src/index.ts optional for backward compatibility
+
+### 3. **Build Configuration Optimization**
+Update rslib.config.ts to generate individual entry points:
+
+```typescript
+export default defineConfig({
+  lib: [
+    // Main entry (for backward compatibility)
+    {
+      bundle: false,
+      dts: true,
+      format: "esm",
+      output: { distPath: { root: "./dist/esm" } }
+    },
+    // Individual component entries
+    {
+      bundle: false,
+      dts: true,
+      format: "esm",
+      output: { distPath: { root: "./dist/esm" } }
+    }
+  ],
+  source: {
+    entry: {
+      index: "./src/index.ts",
+      "components/button/index": "./src/components/button/index.ts",
+      "components/accordion/index": "./src/components/accordion/index.ts"
+    }
+  }
+});
+```
+
+### 4. **Documentation Updates**
+Update documentation to encourage individual imports:
+
+```typescript
+// ❌ Avoid (pulls entire barrel export)
+import { Button, Accordion } from '@codefast/ui';
+
+// ✅ Prefer (optimal tree-shaking)
+import { Button } from '@codefast/ui/button';
+import { Accordion } from '@codefast/ui/accordion';
+```
+
+### 5. **Automated Export Generation**
+Create a script to automatically generate the exports field based on available components:
+
+```javascript
+// scripts/generate-exports.js
+const fs = require('fs');
+const path = require('path');
+
+const componentsDir = './src/components';
+const components = fs.readdirSync(componentsDir);
+
+const exports = {
+  ".": {
+    "import": "./dist/esm/index.js",
+    "require": "./dist/cjs/index.cjs"
+  }
+};
+
+components.forEach(component => {
+  exports[`./${component}`] = {
+    "import": `./dist/esm/components/${component}/index.js`,
+    "require": `./dist/cjs/components/${component}/index.cjs`
+  };
+});
+
+// Update package.json
+```
+
+## Expected Impact
+
+### Before Optimization:
+- Single component import: ~11KB+ initial processing
+- Bundle includes references to all components
+- Suboptimal tree-shaking effectiveness
+
+### After Optimization:
+- Single component import: ~1-5KB processing
+- Bundle includes only required component
+- Optimal tree-shaking effectiveness
+- Estimated 60-80% reduction in bundle size for selective imports
+
+## Implementation Priority
+
+1. **High Priority**: Add individual component exports to package.json
+2. **Medium Priority**: Update build configuration for individual entries
+3. **Low Priority**: Remove barrel export layers (breaking change)
+
+This approach maintains backward compatibility while providing optimal tree-shaking for new usage patterns.