Skip to content

Commit 9411c52

Browse files
tanemtanem
authored
Merge pull request #2878 from tanem/docs
Add copilot instructions and improve documentation language
2 parents 50d295e + 44a650a commit 9411c52

2 files changed

Lines changed: 234 additions & 1 deletion

File tree

‎.github/copilot-instructions.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Copilot Instructions for react-nprogress
2+
3+
## Project Overview
4+
5+
**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:
6+
7+
- **Hook**: `useNProgress` for functional components
8+
- **Render Props**: `NProgress` component with children function
9+
- **HOC**: `withNProgress` higher-order component
10+
11+
The library exports only logic and renders nothing, allowing consumers to implement their own styling and presentation.
12+
13+
## Tech Stack & Dependencies
14+
15+
### Core Technologies
16+
17+
- **TypeScript** (v5.9.2) - Strict mode enabled, targeting ES modules
18+
- **React** (v19+) - Supports React 16.8+ (hooks required), 17, 18, and 19
19+
- **Rollup** - Multi-format bundling (CJS, ES, UMD dev/prod)
20+
21+
### Key Dependencies
22+
23+
- `@babel/runtime` - Runtime helpers for transpiled code
24+
- `hoist-non-react-statics` - HOC static property preservation
25+
26+
### Development Tools
27+
28+
- **ESLint** (flat config) - TypeScript, React, and import sorting rules
29+
- **Jest + @testing-library/react** - Unit testing with jsdom
30+
- **Prettier** - Code formatting
31+
- **mock-raf** - Animation frame mocking for tests
32+
33+
## Project Structure
34+
35+
```
36+
src/
37+
├── index.tsx # Main exports (NProgress, useNProgress, withNProgress)
38+
├── types.ts # Options interface
39+
├── useNProgress.tsx # Core hook implementation
40+
├── NProgress.tsx # Render props component
41+
├── withNProgress.tsx # HOC implementation
42+
├── clamp.ts # Utility: clamp numbers between min/max
43+
├── increment.ts # Utility: progress increment logic
44+
├── createQueue.ts # Utility: async queue management
45+
├── createTimeout.ts # Utility: timeout management
46+
├── useGetSetState.ts # Custom hook for object state (from react-use)
47+
├── useEffectOnce.ts # Custom hook for mount-only effects
48+
└── useUpdateEffect.ts # Custom hook for skipping first effect run
49+
50+
test/ # Jest tests with 100% coverage requirement
51+
examples/ # Usage examples (HOC, Material-UI, Next.js, etc.)
52+
scripts/jest/ # Jest configurations for different build formats
53+
```
54+
55+
## Development Workflow
56+
57+
### Essential Commands
58+
59+
```bash
60+
# Install dependencies
61+
npm install
62+
63+
# Full test suite (checks, lint, build, all format tests)
64+
npm test
65+
66+
# Development commands
67+
npm run check:types # TypeScript type checking
68+
npm run check:format # Check Prettier formatting
69+
npm run lint # ESLint with TypeScript rules
70+
npm run format # Fix linting and format code
71+
72+
# Build process
73+
npm run clean # Remove compiled/dist/coverage
74+
npm run compile # TypeScript compilation to compiled/
75+
npm run bundle # Rollup bundling to dist/
76+
npm run build # Full clean + compile + bundle
77+
78+
# Individual format testing
79+
npm run test:src # Test source TypeScript
80+
npm run test:cjs # Test CommonJS build
81+
npm run test:es # Test ES modules build
82+
npm run test:umd # Test UMD dev build
83+
npm run test:umdprod # Test UMD prod build
84+
```
85+
86+
### Build Process Details
87+
88+
1. **Clean**: Removes `compiled/`, `dist/`, `coverage/`
89+
2. **Compile**: TypeScript → `compiled/` (ES modules, declarations → `dist/`)
90+
3. **Bundle**: Rollup creates 5 builds in `dist/`:
91+
- `react-nprogress.cjs.development.js`
92+
- `react-nprogress.cjs.production.js`
93+
- `react-nprogress.esm.js` (main module export)
94+
- `react-nprogress.umd.development.js`
95+
- `react-nprogress.umd.production.js`
96+
97+
## Code Standards & Guidelines
98+
99+
### TypeScript Configuration
100+
101+
- **Strict mode** enabled with comprehensive flags
102+
- **ES modules** as primary target (`esnext`)
103+
- **React JSX** transform
104+
- **Declaration files** generated for `dist/`
105+
106+
### ESLint Rules (Key Enforcements)
107+
108+
- Import sorting with `simple-import-sort`
109+
- React hooks rules enforcement
110+
- JSX prop sorting
111+
- Key sorting in object literals
112+
- No React import required (automatic JSX transform)
113+
114+
### Testing Requirements
115+
116+
- **100% code coverage** enforced across all build formats
117+
- Tests use `@testing-library/react` with `jsdom`
118+
- Mock `requestAnimationFrame` with `mock-raf`
119+
- Test all three API patterns (hook, render props, HOC)
120+
121+
### File Naming & Organisation
122+
123+
- `.tsx` for React components, `.ts` for utilities
124+
- Small, focused utility functions in separate files
125+
- Custom hooks follow `use*` naming convention
126+
- Export everything through main `index.tsx`
127+
128+
### Language & Documentation Standards
129+
130+
- **Use New Zealand English** at all times (e.g., "colour", "behaviour", "centre", "organisation")
131+
- **In code examples**: Use NZ English for variable names, comments, and user-defined properties where possible
132+
- **Exception**: Standardised API names (CSS properties like `color`, `textAlign: 'center'`, JavaScript APIs) must remain unchanged as they are fixed specifications
133+
- **Avoid marketing speak** - keep documentation simple, grammatically correct, and technically accurate
134+
- Focus on clarity and precision rather than promotional language
135+
- Use proper technical terminology consistently
136+
137+
Example:
138+
```javascript
139+
// Good: NZ English in user code
140+
const progressColour = '#0066cc'
141+
const centredLayout = { textAlign: 'center' } // API name stays 'center'
142+
143+
// Comments and documentation
144+
// Centres the progress bar with custom colour
145+
```
146+
147+
### Commit Message Best Practices
148+
149+
Follow strict line length limits and clear formatting:
150+
151+
```
152+
Subject line (max 50 characters)
153+
154+
Optional body text wrapped at 72 characters. Explain what and why,
155+
not how. Reference any relevant issues.
156+
157+
- Use present tense ("add feature" not "added feature")
158+
- Use imperative mood ("move cursor to..." not "moves cursor to...")
159+
- Capitalise subject line
160+
- No period at end of subject line
161+
- Separate subject from body with blank line
162+
```
163+
164+
## Architecture Patterns
165+
166+
### State Management
167+
168+
- Uses custom `useGetSetState` hook for complex state updates
169+
- Refs for managing imperative APIs (queue, timeout)
170+
- Side effects pattern for coordinating async operations
171+
172+
### Animation Strategy
173+
174+
- Queue-based approach for managing progress updates
175+
- Timeout management for animation timing
176+
- Automatic cleanup on component unmount
177+
178+
### Multi-Format Testing
179+
180+
The project tests against **6 different formats** to ensure broad compatibility:
181+
182+
- Source TypeScript (development)
183+
- CommonJS (dev & prod)
184+
- ES modules
185+
- UMD (dev & prod)
186+
187+
## Common Development Tasks
188+
189+
### Adding New Features
190+
191+
1. Implement in `src/` with TypeScript
192+
2. Export from `index.tsx`
193+
3. Add comprehensive tests covering all API patterns
194+
4. Update types in `types.ts` if needed
195+
5. Run full test suite: `npm test`
196+
197+
### Working with Examples
198+
199+
- Examples are complete applications showing real usage
200+
- Each has its own `package.json` and can be run independently
201+
- Reference for integration patterns and styling approaches
202+
203+
### Debugging Build Issues
204+
205+
- Check TypeScript compilation: `npm run check:types`
206+
- Test specific format: `npm run test:cjs` (or es, umd, etc.)
207+
- Examine `dist/` contents after `npm run build`
208+
- Verify coverage with `npm run test:src`
209+
210+
## Important Notes
211+
212+
### Peer Dependencies
213+
214+
React and ReactDOM are peer dependencies (not bundled). Support matrix:
215+
216+
- React 16.8+ (hooks required), 17, 18, 19
217+
- Matching ReactDOM versions
218+
219+
### No Breaking Changes Without Major Version
220+
221+
This project follows semantic versioning strictly. Even technical refactors bump major versions to prevent consumer issues.
222+
223+
### UMD Builds for Legacy Support
224+
225+
UMD builds support pre-React 19 environments via unpkg CDN with specific React/ReactDOM version requirements.
226+
227+
### State Management Anti-patterns
228+
229+
- Don't use multiple instances without understanding queue isolation
230+
- Always call cleanup functions in effect cleanup
231+
- Be cautious with rapid start/stop toggling
232+
233+
This library is production-ready with extensive testing and serves as a reference for building TypeScript React libraries with multiple distribution formats.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
## Background
1414

15-
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.
15+
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.
1616

1717
## Usage
1818

0 commit comments

Comments
 (0)