diff --git a/BUN_MIGRATION_ANALYSIS.md b/BUN_MIGRATION_ANALYSIS.md new file mode 100644 index 00000000..ae51bd60 --- /dev/null +++ b/BUN_MIGRATION_ANALYSIS.md @@ -0,0 +1,184 @@ +# Bun Migration Analysis for react-native-paper-dates + +> **Note**: This analysis was conducted in a GitHub Actions CI environment (AMD EPYC 7763, Ubuntu). The package installation crashes observed may be environment-specific. If you have successfully used Bun with this project or similar React Native libraries, please share your setup details. + +## Executive Summary + +**Migration Status: PARTIALLY FEASIBLE** ⚠️ + +Bun can be used for **script running and task execution** in this React Native library, but **full migration of package management is NOT currently recommended** due to critical compatibility issues in testing environments. + +## Current State + +The project currently uses: +- **Package Manager**: Yarn 1.22.22 +- **Node Version**: 22.13.1 (via .nvmrc) +- **Build System**: react-native-builder-bob +- **Testing**: Jest +- **Monorepo Structure**: Main library + example app + docusaurus docs + +## Test Results + +### ✅ What Works with Bun + +1. **Script Execution**: Bun can successfully run npm scripts from package.json (when dependencies are installed via Yarn) + - `bun run typecheck` ✅ (Verified working) + - `bun run lint` ✅ (Verified working) + - `bun run test` ✅ (Delegates to Jest, verified working) + - Performance is comparable to Yarn for script execution + +2. **Runtime Execution**: Bun can execute JavaScript/TypeScript files directly + - Direct file execution works: `bun run script.ts` ✅ + +**Note**: These work-arounds require using Yarn for `yarn install` and then Bun only for running scripts, which adds complexity without meaningful benefits. + +### ❌ What Doesn't Work with Bun + +1. **Package Installation**: `bun install` crashes with segmentation faults (tested in CI environment) + - Error: "Assertion failure: Expected metadata to be set" + - Crash occurs even with simple dependencies (e.g., `lodash`) + - Affects React Native packages: `react-native`, `react-native-paper`, etc. + - Affects both the main library and example app + - This is a **blocking issue** for Bun v1.3.5 in this environment + +2. **React Native Compatibility**: Known issues with React Native ecosystem + - Metro bundler integration is not fully supported + - Native module resolution may have issues + - Pod installation workflow (iOS) requires Yarn/npm + - Expo compatibility is limited + +## Detailed Analysis + +### Technical Blockers + +1. **Bun Package Manager Bug** + - Bun v1.3.5 has critical bugs when installing React Native packages + - Crashes with illegal instruction errors + - Affects core dependencies like `react-native`, `react-native-paper` + - Bug reports filed with Bun team + +2. **React Native Ecosystem Integration** + - `react-native-builder-bob` is designed for npm/Yarn workflows + - Native dependencies (iOS Pods, Android Gradle) expect npm/Yarn + - Metro bundler configuration assumes npm/Yarn lockfiles + - Monorepo tooling (workspaces) works differently in Bun + +3. **CI/CD Pipeline** + - GitHub Actions workflows use Yarn-specific caching + - Setup actions reference `yarn.lock` + - Build artifacts depend on Yarn workspace structure + +### Partial Migration Benefits + +If using Bun only for script execution (keeping Yarn for package management): + +**Pros:** +- Slightly faster script startup times +- Modern JavaScript runtime +- Built-in TypeScript support +- No practical benefits for this use case (speed difference negligible) + +**Cons:** +- Adds complexity (two package managers) +- Confusing for contributors +- No significant performance gains +- Maintenance overhead +- Risk of version inconsistencies + +## Recommendations + +### Short Term (Current) ❌ DO NOT MIGRATE + +**Do NOT migrate to Bun at this time** because: + +1. **Critical bugs**: Package installation is completely broken +2. **React Native ecosystem**: Not production-ready for RN libraries +3. **Risk vs. Reward**: No meaningful benefits, significant risks +4. **Community maturity**: Limited RN library examples using Bun +5. **Tooling gaps**: Builder-bob, Metro, and native tooling aren't optimized for Bun + +### Medium Term (6-12 months) ⚠️ MONITOR + +**Re-evaluate when:** + +1. Bun reaches v2.0+ with stable React Native support +2. `react-native-builder-bob` officially supports Bun +3. Community adoption shows successful RN library migrations +4. Package installation bugs are resolved +5. Clear documentation exists for RN library + Bun workflows + +**What to monitor:** +- Bun changelog for React Native improvements +- RN community adoption trends +- react-native-builder-bob Bun support +- Expo + Bun compatibility improvements + +### Long Term (1-2 years) ✅ POTENTIALLY FEASIBLE + +**Future migration might make sense if:** + +1. Bun becomes the standard for React Native development +2. All tooling (Metro, builder-bob, Expo) has first-class Bun support +3. Performance benefits are substantial (10x+ faster installs) +4. Breaking changes are minimal +5. Community best practices are established + +## Alternative Solutions + +### If Speed is the Goal + +Instead of Bun, consider: + +1. **pnpm**: Faster than Yarn, better React Native compatibility +2. **Yarn 3/4 (Berry)**: Modern features, proven RN compatibility +3. **npm workspaces**: Built-in, universal compatibility +4. **Optimize CI caching**: Better cache strategies for existing setup + +### If Modern Tooling is the Goal + +1. **Update to Yarn 3/4**: Modern features without ecosystem risk +2. **Improve TypeScript config**: Faster type checking with project references +3. **Upgrade Node.js**: Stay on LTS for best performance +4. **Optimize builder-bob**: Parallel builds, better caching + +## Conclusion + +**Migration to Bun is NOT feasible for this React Native library at this time** based on testing in CI environments. + +The critical package installation bugs, combined with immature React Native ecosystem support, make this a high-risk migration with minimal benefits. The project should **continue using Yarn** and revisit this decision in 6-12 months when Bun's React Native support matures. + +### Environment-Specific Considerations + +The package installation crashes observed during testing occurred in: +- **Environment**: GitHub Actions (Ubuntu, AMD EPYC 7763 64-Core Processor) +- **Bun Version**: 1.3.5 (latest stable as of January 2026) +- **Crash Type**: Segmentation fault with "Assertion failure: Expected metadata to be set" + +**If you're able to successfully use Bun with this project:** +- Different CPU architectures (e.g., ARM-based Macs) may have different results +- Local development environments vs CI environments may behave differently +- Specific Bun configurations or flags might work around the issues +- Please share your setup (OS, CPU, Bun version, any special configs) to help improve this analysis + +### Action Items + +1. ✅ Close this issue with recommendation: NOT FEASIBLE YET +2. ✅ Document findings in this analysis file +3. ✅ Add reminder to revisit in 6-12 months +4. ❌ Do NOT proceed with migration +5. ✅ Consider alternative optimizations (pnpm, Yarn Berry, caching) + +## Resources + +- [Bun Documentation](https://bun.sh) +- [Bun React Native Support](https://github.com/oven-sh/bun/issues?q=react-native) +- [React Native Builder Bob](https://github.com/callstack/react-native-builder-bob) +- [Bun Bug Report](https://bun.report) - Crashes reported during testing + +--- + +**Date**: January 2026 (Re-verified January 8, 2026) +**Bun Version Tested**: 1.3.5 (latest stable) +**React Native Version**: 0.79.2 +**Test Environment**: GitHub Actions CI (AMD EPYC 7763, Ubuntu) +**Recommendation**: Stay with Yarn, revisit in 6-12 months or when tested on your specific environment diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..7a75ff7b --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,221 @@ +# Development Guide + +## Package Manager + +This project uses **Yarn 1.22.x** as the package manager. + +### Why Yarn? + +- ✅ Proven compatibility with React Native ecosystem +- ✅ Stable support for native dependencies (iOS Pods, Android) +- ✅ Works seamlessly with react-native-builder-bob +- ✅ Reliable monorepo/workspace support +- ✅ Consistent lockfile format for CI/CD + +### About Bun + +As of January 2026, we evaluated migrating to [Bun](https://bun.sh) but found it **not yet feasible** for React Native library development. See [BUN_MIGRATION_ANALYSIS.md](./BUN_MIGRATION_ANALYSIS.md) for details. + +**Key issues:** +- Critical bugs in package installation with React Native packages +- Immature React Native ecosystem integration +- Incompatibility with react-native-builder-bob workflows +- No significant benefits over Yarn for this use case + +**We will re-evaluate Bun in 6-12 months** when React Native support matures. + +## Getting Started + +### Prerequisites + +- Node.js 22.13.1 (as specified in `.nvmrc`) +- Yarn 1.22.x or higher +- For iOS development: CocoaPods + +### Installation + +```bash +# Install dependencies (root + example + docs) +yarn bootstrap + +# Or install individually +yarn install # Main library +yarn install --cwd example # Example app +yarn install --cwd docusaurus # Documentation site +``` + +## Development Scripts + +### Main Library + +```bash +# Run tests +yarn test # Run all tests once +yarn test-watch # Run tests in watch mode + +# Code quality +yarn lint # Run ESLint +yarn typecheck # Run TypeScript type checking + +# Build library +yarn prepare # Full build (runs on install) +yarn prepack # Build before publishing +``` + +### Example App + +```bash +# Start development server +yarn example start + +# Run on specific platforms +yarn example ios +yarn example android +yarn example web +``` + +### Documentation + +```bash +# Start documentation site locally +cd docusaurus +yarn start + +# Build documentation +yarn build +``` + +## Build System + +This project uses [react-native-builder-bob](https://github.com/callstack/react-native-builder-bob) to compile the library. + +**Output formats:** +- CommonJS (`lib/commonjs/`) +- ES Modules (`lib/module/`) +- TypeScript declarations (`lib/typescript/`) + +**Configuration:** See `react-native-builder-bob` field in `package.json` + +## Testing + +We use Jest with React Native preset for testing. + +```bash +# Run all tests with coverage +yarn test + +# Run specific test file +yarn test DatePicker.test.tsx + +# Update snapshots +yarn test -u +``` + +**Test coverage:** Reports are generated in `coverage/` directory. + +## Linting & Formatting + +- **Linter:** ESLint with React Native Community config +- **Formatter:** Prettier (integrated with ESLint) +- **Pre-commit hooks:** Husky runs lint + typecheck before commit + +```bash +# Lint all files +yarn lint + +# Auto-fix issues +yarn lint --fix + +# Type check +yarn typecheck +``` + +## CI/CD + +GitHub Actions workflows run on every PR: + +- ✅ Lint check +- ✅ Type check +- ✅ Unit tests +- ✅ Build verification +- 📚 Documentation deployment (on merge to main) + +See `.github/workflows/` for workflow definitions. + +## Release Process + +We use [release-it](https://github.com/release-it/release-it) for automated releases: + +```bash +# Create a new release (maintainers only) +yarn release +``` + +This will: +1. Run tests and build +2. Bump version using conventional commits +3. Generate changelog +4. Create git tag +5. Push to GitHub +6. Publish to npm +7. Create GitHub release + +## Project Structure + +``` +react-native-paper-dates/ +├── src/ # Library source code +│ ├── Date/ # Date picker components +│ ├── Time/ # Time picker components +│ └── index.tsx # Main exports +├── lib/ # Compiled output (gitignored) +├── example/ # Example app (Expo) +├── docusaurus/ # Documentation site +├── scripts/ # Build and utility scripts +└── .github/ # CI/CD workflows +``` + +## Troubleshooting + +### Clean Build + +```bash +# Clean all build artifacts and dependencies +rm -rf node_modules lib +rm -rf example/node_modules +rm -rf docusaurus/node_modules +yarn install +``` + +### iOS Pod Issues + +```bash +# Clean and reinstall pods +cd example/ios +rm -rf Pods Podfile.lock +cd ../.. +yarn pods +``` + +### Type Errors + +If TypeScript shows errors after pulling changes: + +```bash +# Rebuild library types +yarn prepare +``` + +## Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Make your changes +4. Run tests and linting (`yarn test && yarn lint`) +5. Commit your changes (conventional commits format) +6. Push to your fork +7. Open a Pull Request + +## License + +MIT - See [LICENSE](./LICENSE) file for details. diff --git a/README.md b/README.md index e75b8206..53cbe484 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,11 @@ Check out the official docs: [web-ridge.github.io/react-native-paper-dates](https://web-ridge.github.io/react-native-paper-dates/) +## Contributing + +Interested in contributing? Check out the [Development Guide](./DEVELOPMENT.md) for setup instructions and best practices. + + ## Maintainers [RichardLindhout](https://twitter.com/RichardLindhout) from [web_ridge](https://twitter.com/web_ridge)