diff --git a/.changeset/purple-bats-fetch.md b/.changeset/purple-bats-fetch.md new file mode 100644 index 0000000000..a845151cc8 --- /dev/null +++ b/.changeset/purple-bats-fetch.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..c05e798c40 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,271 @@ +# GitHub Copilot Instructions for rnx-kit + +## Project Overview + +`rnx-kit` is a collection of battle-tested React Native development tools +created by Microsoft engineers for optimizing React Native development at scale. +This is a **monorepo** using: + +- **Nx v20.3.3** (patched) for build orchestration and project management +- **Yarn v4.6.0** as the package manager with workspaces +- **TypeScript v5.0+** as the primary language with strict configuration +- **Node.js ≥18.12** runtime requirement + +### Core Architecture + +- **Nx Monorepo**: Build orchestration with automatic project dependencies +- **Workspace Dependencies**: Internal packages use `workspace:*` references +- **Common Build Scripts**: All packages use `@rnx-kit/scripts` for consistency +- **Platform-Specific Tools**: Separate `tools-*` packages for iOS, Android, + Windows, etc. + +## Repository Structure + +``` +packages/ # Main published packages (@rnx-kit/* scope) +incubator/ # Experimental/beta packages +scripts/ # Build and maintenance scripts +docsite/ # Docusaurus documentation site +``` + +### Key Packages Categories + +- **Dependency Management**: `align-deps`, `dep-check` +- **Metro Bundling**: `metro-config`, `metro-serializer*`, `metro-plugin-*` +- **Build Tools**: `cli`, `build` (incubator), native platform tools +- **Development Tools**: `eslint-config`, `jest-preset`, `babel-preset-*` +- **React Native Utilities**: `react-native-*`, `tools-*` + +## Build System & Development Commands + +### Root-Level Commands + +```bash +yarn build # Build all packages using Nx +yarn test # Build and test all packages +yarn lint # Lint all packages with ESLint +yarn bundle # Bundle packages for distribution +yarn format # Format code with Prettier +yarn clean # Clean build artifacts (git clean -dfqx) +yarn new-package # Create new package from template +yarn change # Create Changeset entry for versioning +yarn rnx-align-deps # Align dependencies across workspace +yarn show-affected # Show Nx affected projects +``` + +### Package-Level Commands + +Each package supports these scripts via `@rnx-kit/scripts`: + +- `yarn build` - TypeScript compilation to `lib/` +- `yarn lint` - ESLint with `@rnx-kit/eslint-config` +- `yarn test` - Jest tests with `@rnx-kit/jest-preset` +- `yarn format` - Prettier formatting +- `bundle` - Bundle for distribution (where applicable) + +### Nx Integration Details + +- **Build Dependencies**: Packages automatically depend on upstream builds +- **Affected Builds**: Use `nx affected --targets build,test` for incremental CI +- **Caching**: Build and test results are cached for performance +- **Target Defaults**: Defined in `nx.json` with dependency ordering + +## Development Guidelines + +### Code Style & Standards + +- **Prettier** for formatting with shared config at `.github/prettierrc.json` +- **ESLint** with `@rnx-kit/eslint-config` (shared across all packages) +- **TypeScript** with strict configuration +- Single quotes for JavaScript/TypeScript (`'` not `"`) +- 2-space indentation +- Trim trailing whitespace + +### Package Structure Standards + +Every package follows this structure: + +``` +package-name/ +├── package.json # @rnx-kit/package-name scope +├── eslint.config.js # Points to @rnx-kit/eslint-config +├── tsconfig.json # TypeScript configuration +├── src/ # Source code +│ └── index.ts # Main entry point +├── lib/ # Compiled output (gitignored) +└── test/ # Jest tests + └── *.test.ts +``` + +### Common Scripts + +All packages use `@rnx-kit/scripts` for consistent build commands: + +- `build`: Compile TypeScript to `lib/` with source maps +- `format`: Run Prettier with organize imports +- `lint`: Run ESLint with `@rnx-kit/eslint-config` +- `test`: Run Jest tests with `@rnx-kit/jest-preset` +- `bundle`: Bundle for distribution (where applicable) + +### Nx Integration + +- Use `nx run-many --target ` for bulk operations +- Dependencies between packages are automatically detected +- Build cache is enabled for performance +- Use `nx affected` for incremental builds in CI +- Build order handled automatically based on package dependencies + +## Filing & Naming Conventions + +### Package Naming + +- All packages use `@rnx-kit/` scope +- Use kebab-case: `@rnx-kit/metro-plugin-typescript` +- Tools packages: `@rnx-kit/tools-` (e.g., `tools-android`) +- Metro plugins: `@rnx-kit/metro-plugin-` +- CLI tools often have `rnx-` prefix in bin name + +### File Extensions + +- `.ts` for TypeScript source files +- `.js` for JavaScript config files (eslint, jest, etc.) +- `.test.ts` for Jest tests +- `.d.ts` for type definitions + +### Import/Export Patterns + +- Use `export` from main `src/index.ts` for public API +- Internal utilities in separate files under `src/` +- Prefer named exports over default exports +- Use barrel exports in index files + +## Dependencies Management + +### Workspace Dependencies + +- Use `workspace:*` for internal package references +- External deps in `devDependencies` where possible +- Dependencies are aligned across workspace using `align-deps` tool +- Avoid duplicate dependencies (checked by `align-deps`) + +### Common Dependencies + +- `@rnx-kit/console` for logging utilities +- `@rnx-kit/tools-*` for platform-specific utilities +- React Native community packages where applicable + +### Key Development Dependencies + +- **ESLint**: ^9.0.0 with custom `@rnx-kit/eslint-config` +- **Prettier**: ^3.0.0 with `prettier-plugin-organize-imports` +- **Jest**: ^29.2.1 with `@rnx-kit/jest-preset` +- **Changesets**: ^2.22.0 for version management + +### Testing Patterns + +### Jest Configuration + +- All packages use `@rnx-kit/jest-preset` +- Tests in `/test/` directory alongside source +- Use `.test.ts` suffix for test files +- Mock external dependencies appropriately +- Test coverage tracked per package + +### Test Structure + +```typescript +describe("FeatureName", () => { + it("should handle expected case", () => { + // Arrange, Act, Assert pattern + }); +}); +``` + +## Documentation Standards + +### README Structure + +Each package should include: + +1. Brief description and purpose +2. Installation instructions +3. Usage examples +4. Configuration options +5. API reference (auto-generated where possible) + +### API Documentation + +- Use TSDoc comments for public APIs +- Include `@param` and `@returns` tags +- Provide usage examples in comments + +## Build & CI Considerations + +### Build Process + +- TypeScript compilation to `lib/` directory +- Type definitions (`.d.ts`) included in published packages +- Source maps for debugging +- Build order handled automatically by Nx based on dependencies + +### Publishing + +- Uses Changesets for version management and publishing +- Automated releases via GitHub Actions +- Change logs generated from changeset descriptions +- Semantic versioning with automated changelog generation + +### Performance + +- Nx caching for build performance +- Incremental builds using `nx affected` +- Tree-shakable exports where possible +- Build artifacts cached across CI runs + +## Platform-Specific Notes + +### React Native + +- Support multiple RN versions where possible +- Handle platform differences (iOS, Android, Windows, macOS) +- Use React Native community standards +- Native module configuration for each platform +- Multiple React Native version support patterns + +### Metro Integration + +- Follow Metro plugin architecture +- Handle both development and production builds +- Respect Metro's transformer and serializer APIs +- Metro plugins follow established plugin architecture patterns + +### Node.js + +- Minimum Node 18.12 support +- Use modern Node.js APIs appropriately +- Handle different package managers (yarn, npm, pnpm) + +## Error Handling + +### Logging + +- Use `@rnx-kit/console` for consistent output +- Include actionable error messages +- Use appropriate log levels (error, warn, info) + +### Error Messages + +- Provide clear, actionable error messages +- Include context and suggested fixes +- Link to documentation where helpful + +## When Contributing + +1. Run `yarn new-package ` for new packages +2. Use `yarn change` to create changeset entries +3. Follow the existing package patterns and structure +4. Ensure tests pass and code is properly formatted +5. Update documentation as needed + +Remember: This is a Microsoft OSS project serving React Native developers at +scale. Prioritize reliability, performance, and developer experience. diff --git a/.gitignore b/.gitignore index 66c3eeb8f1..b5745b08bb 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,6 @@ msbuild.binlog node_modules/ rnx-kit-workspaces.json !**/__fixtures__/**/node_modules/ + +.cursor/rules/nx-rules.mdc +.github/instructions/nx.instructions.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 1da42fe8ef..83f7faa316 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -76,5 +76,6 @@ "syncpack", "transpiles", "unconfigured" - ] + ], + "nxConsole.generateAiAgentRules": true } diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..85192e3a13 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,149 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +`rnx-kit` is a collection of battle-tested React Native development tools created by Microsoft engineers. This is a **monorepo** containing tools for dependency management, bundling, native builds, and development workflow optimization across React Native projects at scale. + +## Repository Architecture + +### High-Level Structure +``` +packages/ # Main published packages (@rnx-kit/* scope) +incubator/ # Experimental/beta packages +scripts/ # Build and maintenance scripts +docsite/ # Docusaurus documentation site +``` + +### Key Package Categories +- **Dependency Management**: `align-deps`, `dep-check` +- **Metro Bundling**: `metro-config`, `metro-serializer*`, `metro-plugin-*` +- **Build Tools**: `cli`, `build` (incubator), native platform tools +- **Development Tools**: `eslint-config`, `jest-preset`, `babel-preset-*` +- **React Native Utilities**: `react-native-*`, `tools-*` + +### Architecture Patterns +- **Nx Monorepo**: Uses Nx for build orchestration with project dependencies +- **Workspace Dependencies**: Internal packages use `workspace:*` references +- **Common Build Scripts**: All packages use `@rnx-kit/scripts` for consistent commands +- **Platform-Specific Tools**: Separate `tools-*` packages for iOS, Android, Windows, etc. + +## Build System & Commands + +### Primary Commands (Root Level) +```bash +yarn build # Build all packages using Nx +yarn test # Build and test all packages +yarn lint # Lint all packages +yarn bundle # Bundle packages for distribution +yarn format # Format code with Prettier +yarn clean # Clean build artifacts (git clean -dfqx) +``` + +### Development Commands +```bash +yarn new-package # Create new package from template +yarn change # Create Changeset entry for versioning +yarn change:check # Check changeset status +yarn rnx-align-deps # Align dependencies across workspace +yarn show-affected # Show Nx affected projects +``` + +### Package-Level Commands +Each package supports standard scripts via `@rnx-kit/scripts`: +- `yarn build` - TypeScript compilation to `lib/` +- `yarn lint` - ESLint with `@rnx-kit/eslint-config` +- `yarn test` - Jest tests with `@rnx-kit/jest-preset` +- `yarn format` - Prettier formatting +- `bundle` - Bundle for distribution (where applicable) + +### Nx Integration Details +- **Build Dependencies**: Packages automatically depend on upstream builds +- **Affected Builds**: Use `nx affected --targets build,test` for incremental CI +- **Caching**: Build and test results are cached for performance +- **Target Defaults**: Defined in `nx.json` with dependency ordering + +## Development Workflow + +### Package Structure Standards +Every package follows this structure: +``` +package-name/ +├── package.json # @rnx-kit/package-name scope +├── eslint.config.js # Points to @rnx-kit/eslint-config +├── tsconfig.json # TypeScript configuration +├── src/ # Source code +│ └── index.ts # Main entry point +├── lib/ # Compiled output (gitignored) +└── test/ # Jest tests + └── *.test.ts +``` + +### Code Style & Standards +- **Prettier** formatting with shared config at `.github/prettierrc.json` +- **ESLint** with `@rnx-kit/eslint-config` (applied to all packages) +- **TypeScript** strict configuration +- Single quotes, 2-space indentation, trailing whitespace trimmed + +### Testing Strategy +- **Jest Preset**: All packages use `@rnx-kit/jest-preset` +- **Test Location**: Tests in `/test/` directory with `.test.ts` suffix +- **Coverage**: Test coverage tracked per package + +### Versioning & Publishing +- **Changesets**: Use `yarn change` to create changeset entries +- **Automated Publishing**: GitHub Actions handle releases +- **Semantic Versioning**: Follows semver with automated changelog generation + +## Key Dependencies & Tooling + +### Core Technologies +- **Nx**: ^20.3.3 (patched) - Build orchestration and monorepo management +- **Yarn v4**: Package manager with workspaces +- **TypeScript**: ^5.0.0 - Primary language across all packages +- **Node.js**: >=18.12 runtime requirement + +### Development Dependencies +- **ESLint**: ^9.0.0 with custom `@rnx-kit/eslint-config` +- **Prettier**: ^3.0.0 with `prettier-plugin-organize-imports` +- **Jest**: ^29.2.1 with `@rnx-kit/jest-preset` +- **Changesets**: ^2.22.0 for version management + +### React Native Integration +- Multiple React Native version support patterns +- Platform-specific handling (iOS, Android, Windows, macOS) +- Metro bundler integration and plugin architecture +- Native module configuration for platforms + +## Important Notes + +### Package Management +- Use `yarn new-package ` to create new packages from template +- Internal dependencies must use `workspace:*` syntax +- Dependencies are aligned across workspace using `align-deps` tool +- Package names use `@rnx-kit/` scope with kebab-case + +### Build Considerations +- Nx handles build order based on package dependencies +- TypeScript builds output to `lib/` directory with source maps +- Type definitions (`.d.ts`) included in published packages +- Build cache significantly improves performance + +### Development Environment +- Node.js ≥18.12 required +- Yarn v4.6.0 specified as package manager +- Git hooks may be configured for pre-commit validation +- All packages are private except published ones + +### Metro & React Native +- Metro plugins follow established plugin architecture patterns +- Support for multiple React Native versions across packages +- Platform-specific configurations handled per tool +- Native module integration for iOS/Android/Windows/macOS + +### CI/CD Integration +- Nx affected commands optimize CI build times +- Changeset-based automated publishing workflow +- Build artifacts cached across CI runs +- Comprehensive linting and testing in CI pipeline \ No newline at end of file diff --git a/nx.json b/nx.json index 91b9cedf23..d727d6c20c 100644 --- a/nx.json +++ b/nx.json @@ -43,5 +43,8 @@ "@nx/js": { "analyzeSourceFiles": false } + }, + "ai": { + "generateAiAgentRules": true } }