From 1fec3df62d7caef0ffcc8c4a07e05881f35d97ad Mon Sep 17 00:00:00 2001 From: Tane Morgan <464864+tanem@users.noreply.github.com> Date: Sun, 12 Oct 2025 15:20:52 +1300 Subject: [PATCH 1/2] Add copilot instructions for development workflow Document project structure, tech stack, and development practices including TypeScript configuration, testing requirements, and build process. Establish language standards requiring NZ English and technical documentation without promotional language. Provides coding agents with necessary context for efficient development within established project conventions. --- .github/copilot-instructions.md | 233 ++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..8a93a240c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,233 @@ +# Copilot Instructions for react-nprogress + +## Project Overview + +**react-nprogress** is a React primitive for building slim progress bars. It's a TypeScript-based React port of rstacruz/nprogress that provides three API patterns: + +- **Hook**: `useNProgress` for functional components +- **Render Props**: `NProgress` component with children function +- **HOC**: `withNProgress` higher-order component + +The library exports only logic and renders nothing, allowing consumers to implement their own styling and presentation. + +## Tech Stack & Dependencies + +### Core Technologies + +- **TypeScript** (v5.9.2) - Strict mode enabled, targeting ES modules +- **React** (v19+) - Supports React 16.8+ (hooks required), 17, 18, and 19 +- **Rollup** - Multi-format bundling (CJS, ES, UMD dev/prod) + +### Key Dependencies + +- `@babel/runtime` - Runtime helpers for transpiled code +- `hoist-non-react-statics` - HOC static property preservation + +### Development Tools + +- **ESLint** (flat config) - TypeScript, React, and import sorting rules +- **Jest + @testing-library/react** - Unit testing with jsdom +- **Prettier** - Code formatting +- **mock-raf** - Animation frame mocking for tests + +## Project Structure + +``` +src/ +├── index.tsx # Main exports (NProgress, useNProgress, withNProgress) +├── types.ts # Options interface +├── useNProgress.tsx # Core hook implementation +├── NProgress.tsx # Render props component +├── withNProgress.tsx # HOC implementation +├── clamp.ts # Utility: clamp numbers between min/max +├── increment.ts # Utility: progress increment logic +├── createQueue.ts # Utility: async queue management +├── createTimeout.ts # Utility: timeout management +├── useGetSetState.ts # Custom hook for object state (from react-use) +├── useEffectOnce.ts # Custom hook for mount-only effects +└── useUpdateEffect.ts # Custom hook for skipping first effect run + +test/ # Jest tests with 100% coverage requirement +examples/ # Usage examples (HOC, Material-UI, Next.js, etc.) +scripts/jest/ # Jest configurations for different build formats +``` + +## Development Workflow + +### Essential Commands + +```bash +# Install dependencies +npm install + +# Full test suite (checks, lint, build, all format tests) +npm test + +# Development commands +npm run check:types # TypeScript type checking +npm run check:format # Check Prettier formatting +npm run lint # ESLint with TypeScript rules +npm run format # Fix linting and format code + +# Build process +npm run clean # Remove compiled/dist/coverage +npm run compile # TypeScript compilation to compiled/ +npm run bundle # Rollup bundling to dist/ +npm run build # Full clean + compile + bundle + +# Individual format testing +npm run test:src # Test source TypeScript +npm run test:cjs # Test CommonJS build +npm run test:es # Test ES modules build +npm run test:umd # Test UMD dev build +npm run test:umdprod # Test UMD prod build +``` + +### Build Process Details + +1. **Clean**: Removes `compiled/`, `dist/`, `coverage/` +2. **Compile**: TypeScript → `compiled/` (ES modules, declarations → `dist/`) +3. **Bundle**: Rollup creates 5 builds in `dist/`: + - `react-nprogress.cjs.development.js` + - `react-nprogress.cjs.production.js` + - `react-nprogress.esm.js` (main module export) + - `react-nprogress.umd.development.js` + - `react-nprogress.umd.production.js` + +## Code Standards & Guidelines + +### TypeScript Configuration + +- **Strict mode** enabled with comprehensive flags +- **ES modules** as primary target (`esnext`) +- **React JSX** transform +- **Declaration files** generated for `dist/` + +### ESLint Rules (Key Enforcements) + +- Import sorting with `simple-import-sort` +- React hooks rules enforcement +- JSX prop sorting +- Key sorting in object literals +- No React import required (automatic JSX transform) + +### Testing Requirements + +- **100% code coverage** enforced across all build formats +- Tests use `@testing-library/react` with `jsdom` +- Mock `requestAnimationFrame` with `mock-raf` +- Test all three API patterns (hook, render props, HOC) + +### File Naming & Organisation + +- `.tsx` for React components, `.ts` for utilities +- Small, focused utility functions in separate files +- Custom hooks follow `use*` naming convention +- Export everything through main `index.tsx` + +### Language & Documentation Standards + +- **Use New Zealand English** at all times (e.g., "colour", "behaviour", "centre", "organisation") +- **In code examples**: Use NZ English for variable names, comments, and user-defined properties where possible +- **Exception**: Standardised API names (CSS properties like `color`, `textAlign: 'center'`, JavaScript APIs) must remain unchanged as they are fixed specifications +- **Avoid marketing speak** - keep documentation simple, grammatically correct, and technically accurate +- Focus on clarity and precision rather than promotional language +- Use proper technical terminology consistently + +Example: +```javascript +// Good: NZ English in user code +const progressColour = '#0066cc' +const centredLayout = { textAlign: 'center' } // API name stays 'center' + +// Comments and documentation +// Centres the progress bar with custom colour +``` + +### Commit Message Best Practices + +Follow strict line length limits and clear formatting: + +``` +Subject line (max 50 characters) + +Optional body text wrapped at 72 characters. Explain what and why, +not how. Reference any relevant issues. + +- Use present tense ("add feature" not "added feature") +- Use imperative mood ("move cursor to..." not "moves cursor to...") +- Capitalise subject line +- No period at end of subject line +- Separate subject from body with blank line +``` + +## Architecture Patterns + +### State Management + +- Uses custom `useGetSetState` hook for complex state updates +- Refs for managing imperative APIs (queue, timeout) +- Side effects pattern for coordinating async operations + +### Animation Strategy + +- Queue-based approach for managing progress updates +- Timeout management for animation timing +- Automatic cleanup on component unmount + +### Multi-Format Testing + +The project tests against **6 different formats** to ensure broad compatibility: + +- Source TypeScript (development) +- CommonJS (dev & prod) +- ES modules +- UMD (dev & prod) + +## Common Development Tasks + +### Adding New Features + +1. Implement in `src/` with TypeScript +2. Export from `index.tsx` +3. Add comprehensive tests covering all API patterns +4. Update types in `types.ts` if needed +5. Run full test suite: `npm test` + +### Working with Examples + +- Examples are complete applications showing real usage +- Each has its own `package.json` and can be run independently +- Reference for integration patterns and styling approaches + +### Debugging Build Issues + +- Check TypeScript compilation: `npm run check:types` +- Test specific format: `npm run test:cjs` (or es, umd, etc.) +- Examine `dist/` contents after `npm run build` +- Verify coverage with `npm run test:src` + +## Important Notes + +### Peer Dependencies + +React and ReactDOM are peer dependencies (not bundled). Support matrix: + +- React 16.8+ (hooks required), 17, 18, 19 +- Matching ReactDOM versions + +### No Breaking Changes Without Major Version + +This project follows semantic versioning strictly. Even technical refactors bump major versions to prevent consumer issues. + +### UMD Builds for Legacy Support + +UMD builds support pre-React 19 environments via unpkg CDN with specific React/ReactDOM version requirements. + +### State Management Anti-patterns + +- Don't use multiple instances without understanding queue isolation +- Always call cleanup functions in effect cleanup +- Be cautious with rapid start/stop toggling + +This library is production-ready with extensive testing and serves as a reference for building TypeScript React libraries with multiple distribution formats. From 44a650a774e1bc4f02ce0920296e77d392832c12 Mon Sep 17 00:00:00 2001 From: Tane Morgan <464864+tanem@users.noreply.github.com> Date: Sun, 12 Oct 2025 15:21:09 +1300 Subject: [PATCH 2/2] Use technical language in README background Replace promotional phrase "giving you complete control" with technical description "allowing consumers to implement their own rendering" in Background section. Maintains factual tone consistent with documentation standards. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c94efacdd..d718de9e1 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ## Background -This is a React port of [rstacruz](https://github.com/rstacruz)'s [`nprogress`](https://github.com/rstacruz/nprogress) module. It exposes an API that encapsulates the logic of `nprogress` and renders nothing, giving you complete control over rendering. +This is a React port of [rstacruz](https://github.com/rstacruz)'s [`nprogress`](https://github.com/rstacruz/nprogress) module. It exposes an API that encapsulates the logic of `nprogress` and renders nothing, allowing consumers to implement their own rendering. ## Usage