MODERN_STANDARDS_MIGRATION_PLAN.md

Modernize Build System to 2025 Standards

Problem Statement

Current TypeScript build system generates warnings: "Package type is set to 'commonjs' but 'esm' format is included. Going to use 'cjs' format instead." This indicates our dual CJS/ESM build configuration doesn't align with 2025 ecosystem standards.

Solution Overview

Migrate from current dist/ + dist/esm/ structure to separate dist/cjs/ and dist/esm/ directories with explicit .cjs/.mjs file extensions. This aligns with Node.js, Webpack, and TypeScript 2025 recommendations while maintaining all existing functionality.

Technical Approach

• New Structure: dist/cjs/ (CommonJS) and dist/esm/ (ES Modules) with format-specific package.json files
• File Extensions: Use explicit .cjs and .mjs extensions instead of ambiguous .js
• Migration Strategy: Complete cutover across all 15 packages simultaneously to avoid workspace inconsistencies
• Import Compatibility: Zero breaking changes - all existing barrel and granular imports continue working

Business Value

• Eliminates TypeScript compiler warnings (improved developer experience)
• Future-proofs packages for ecosystem evolution (Node.js v22/v23+)
• Better compatibility with modern bundlers (webpack 5+, rspack, vite)
• Maintains 100% backward compatibility for consumers

Acceptance Criteria

• [ ] All 15 packages build without TypeScript warnings
• [ ] Existing import patterns work unchanged: import { Section } from '@pkg' and import { Section } from '@pkg/Section'
• [ ] Demo app and external consumers function without code changes
• [ ] Workspace development (symlinks) resolves correctly
• [ ] Published packages use modern exports field with .cjs/.mjs paths

Scope

Packages Affected: All 15 public packages in the monorepo
Files Modified: ~45 configuration files (package.json, project.json, tsconfig.*.json) + 3 build executors

Risks & Mitigation

• Risk: Potential bundler compatibility issues with .mjs files
• Mitigation: .mjs is well-supported in webpack 5+, vite, rspack (our target bundlers)
• Rollback: Git branch strategy enables quick revert if issues arise