Skip to content

Commit 1483f12

Browse files
timowestnostotimowestnosto
authored
Merge pull request #507 from Nosto/copilot/fix-506
feat: create comprehensive GitHub Copilot instructions and add Node.js engine requirement
2 parents a952dbb + 685ab49 commit 1483f12

2 files changed

Lines changed: 119 additions & 17 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 116 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,123 @@
11
# Instructions for GitHub Copilot
22

3-
## Coding standards
3+
**ALWAYS follow these instructions first and only use additional search or bash commands if the information here is incomplete or found to be in error.**
44

5-
* Use closures over classes
6-
* Utilize type inference in return types, except for functions with multiple return statements
7-
* Use utility types to derive types from constants
8-
* Use const (and let) over var
9-
* Avoid 'any' type usage
10-
* Use async/await instead of Promise chaining
11-
* Use individual named exports over bulk exports
12-
* Favor named exports over default exports
5+
## Repository Overview
136

14-
## Testing
7+
Nosto React is a React component library for implementing Nosto personalization features. It's a TypeScript library that builds both ES and UMD modules using Vite, with comprehensive test coverage requirements (80% threshold).
158

16-
* Use vitest as the test framework
17-
* Use 'describe' and 'it' for test structure
18-
* Use 'beforeEach' for setup
19-
* Use 'afterEach' for cleanup
20-
* Use 'expect' for assertions
9+
## Working Effectively
2110

22-
## Commits
11+
### Initial Setup and Dependencies
12+
- Bootstrap the repository: `npm ci` -- installs dependencies and runs initial build. Takes ~90 seconds. NEVER CANCEL. Set timeout to 3+ minutes.
13+
- Alternative clean install: `npm install` (if npm ci fails)
14+
- Node.js requirement: Use Node.js 22 (as specified in CI workflow). Current system has Node v20 which works but CI uses v22.
2315

24-
* Use conventional commits format: `<type>(<scope>): <subject>`
16+
### Building
17+
- Full build: `npm run build` -- includes TypeScript compilation, ESLint, Vite bundling, and TypeDoc generation. Takes ~12 seconds. NEVER CANCEL. Set timeout to 5+ minutes.
18+
- Type checking only: `npm run typecheck` -- runs TypeScript compiler without output. Takes ~2 seconds.
19+
- Clean build: `npm run clean && npm run build` -- removes dist directory first
20+
- Build outputs: Creates `dist/index.es.js`, `dist/index.umd.js`, and `dist/index.d.ts`
21+
22+
### Testing
23+
- Run tests: `npm test` -- runs vitest with coverage in silent mode. **WARNING**: Tests currently fail in sandbox environments due to network connectivity to `connect.nosto.com` and missing browser globals. This is expected in isolated environments.
24+
- Verbose tests: `npm run test-loud` -- runs tests with full output
25+
- Test coverage thresholds: 80% for statements, branches, lines, and functions
26+
- Test setup: Uses JSDOM for browser environment simulation (see `spec/setup.js`)
27+
28+
### Development Server
29+
- Start dev server: `npm run dev` -- starts Vite development server on http://localhost:5173/. Starts in ~1 second.
30+
- Preview built version: `npm run preview` -- serves the built library
31+
32+
### Code Quality
33+
- Lint code: `npm run lint` -- runs ESLint on TypeScript files. Takes ~1 second. Currently has 1 warning about unused eslint-disable directive.
34+
- Format check: `npm run prettier` -- checks Prettier formatting. Takes ~1 second. Currently shows formatting issues in several files.
35+
- Format fix: `npm run prettier:fix` -- applies Prettier formatting
36+
37+
### Documentation
38+
- Generate docs: `npm run typedoc` -- generates TypeDoc documentation in `./docs` directory. Takes ~4 seconds.
39+
- Documentation is published to GitHub Pages at: https://nosto.github.io/nosto-react/
40+
41+
## Validation
42+
43+
### CRITICAL Testing Limitations
44+
- **Tests fail in isolated environments**: The test suite requires network access to `connect.nosto.com` and full browser environment globals. Test failures in sandbox environments are EXPECTED and not indicative of code issues.
45+
- **CI Environment**: The GitHub Actions CI pipeline (`.github/workflows/ci.yml`) runs tests successfully with proper environment setup.
46+
47+
### Manual Validation Requirements
48+
- Always run `npm run build` to ensure TypeScript compilation and bundling work
49+
- Always run `npm run lint` and check for new warnings or errors
50+
- Always run `npm run typecheck` for TypeScript validation
51+
- Test development server starts: `npm run dev` should start server on localhost:5173
52+
- Verify documentation generates: `npm run typedoc` should create docs in `./docs`
53+
54+
### Pre-commit Validation
55+
- Always run `npm run lint` before committing - CI will fail if linting errors exist
56+
- Use conventional commit format: `<type>(<scope>): <subject>` (enforced by commitlint)
57+
- Husky runs commit message validation via `.husky/commit-msg`
58+
59+
## Repository Structure
60+
61+
### Key Directories
62+
- `src/` - Source code
63+
- `src/components/` - React components (NostoProvider, NostoPlacement, etc.)
64+
- `src/hooks/` - React hooks (useNosto*, useLoadClientScript, etc.)
65+
- `src/utils/` - Utility functions and types
66+
- `src/context.ts` - React context for Nosto
67+
- `src/index.ts` - Main export file
68+
- `spec/` - Test files (vitest)
69+
- `dist/` - Build output (ES/UMD modules + TypeScript definitions)
70+
- `docs/` - Generated TypeDoc documentation
71+
72+
### Important Files
73+
- `package.json` - Dependencies and scripts
74+
- `vite.config.js` - Vite configuration for building
75+
- `tsconfig.json` - TypeScript configuration
76+
- `eslint.config.mjs` - ESLint configuration
77+
- `.prettierrc` - Prettier configuration
78+
- `.github/workflows/ci.yml` - CI pipeline configuration
79+
80+
## Coding Standards
81+
82+
- Use closures over classes
83+
- Utilize type inference in return types, except for functions with multiple return statements
84+
- Use utility types to derive types from constants
85+
- Use const (and let) over var
86+
- Avoid 'any' type usage
87+
- Use async/await instead of Promise chaining
88+
- Use individual named exports over bulk exports
89+
- Favor named exports over default exports
90+
91+
## Testing Standards
92+
93+
- Use vitest as the test framework
94+
- Use 'describe' and 'it' for test structure
95+
- Use 'beforeEach' for setup
96+
- Use 'afterEach' for cleanup
97+
- Use 'expect' for assertions
98+
- Test files located in `spec/` directory
99+
- Tests require JSDOM environment for React component testing
100+
101+
## Common Commands Reference
102+
103+
```bash
104+
# Initial setup (90 seconds, NEVER CANCEL)
105+
npm ci
106+
107+
# Build and validate (12 seconds)
108+
npm run build
109+
110+
# Quick validation
111+
npm run typecheck # TypeScript (2 seconds)
112+
npm run lint # ESLint (1 second)
113+
114+
# Development
115+
npm run dev # Start dev server (1 second)
116+
117+
# Documentation
118+
npm run typedoc # Generate docs (4 seconds)
119+
120+
# Testing (fails in sandbox - see validation section)
121+
npm test # Run tests with coverage
122+
npm run test-loud # Verbose test output
123+
```

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
"nosto",
1313
"personalisation"
1414
],
15+
"engines": {
16+
"node": ">=22.0.0"
17+
},
1518
"scripts": {
1619
"dev": "vite",
1720
"build": "tsc && npm run lint && vite build && npm run typedoc",

0 commit comments

Comments
 (0)