Skip to content

Commit 6325a6a

Browse files
ksinderksinder
authored
Add Copilot instructions file for repo (#610)
## Description This PR commits the result of a `.github/copilot-instructions.md` file generated with the help of Cursor agent. This can help improve the quality Copilot code reviews and flag certain files that are generated and should not be commented on, e.g. `src/api-endpoints.ts` General context: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#creating-repository-wide-custom-instructions-1 ## How was this change tested? - [ ] Automated test (unit, integration, etc.) - [x] Manual test (provide reproducible testing steps below) N/A; we can manually test this by seeing how Copilot code reviewer behaves. ## Screenshots N/A
1 parent 88a6b3f commit 6325a6a

File tree

2 files changed

+155
-2
lines changed

2 files changed

+155
-2
lines changed

‎.cspell.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// cSpell Settings
22
{
33
// Version of the setting file. Always 0.1
4-
"version": "0.1",
4+
"version": "0.2",
55
// language - current active spelling language
66
"language": "en",
77
// words - list of words to be always considered correct
@@ -13,7 +13,8 @@
1313
"blackmad",
1414
"octokit",
1515
"printf",
16-
"is_toggleable"
16+
"is_toggleable",
17+
"typecheck"
1718
],
1819
// flagWords - list of words to be always considered incorrect
1920
// This is useful for offensive words and common spelling errors.

‎.github/copilot-instructions.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Notion SDK for JavaScript - Copilot Instructions
2+
3+
## Repository Overview
4+
5+
This is the official Notion SDK for JavaScript, a client library for interacting with the Notion API. The SDK provides a simple and type-safe interface to all Notion API endpoints.
6+
7+
**Repository Details:**
8+
- **Type**: Node.js TypeScript SDK
9+
- **Package**: `@notionhq/client`
10+
- **Target Runtime**: Node.js ≥ 18
11+
- **TypeScript**: ≥ 5.9
12+
- **Build System**: TypeScript compiler (tsc)
13+
- **Test Framework**: Jest with ts-jest
14+
- **Code Style**: Prettier (no semicolons, ES5 trailing commas, LF line endings)
15+
- **Linting**: ESLint with TypeScript rules + cspell for spell checking
16+
17+
## Important Files and Warnings
18+
19+
### ⚠️ Generated Files - DO NOT EDIT
20+
21+
- `src/api-endpoints.ts` - This is an auto-generated file (see header comment). Never suggest changes to this file.
22+
- All files in `build/` directory - These are compiled outputs
23+
24+
### Key Source Files
25+
26+
- `src/Client.ts` - Main client implementation
27+
- `src/index.ts` - Public API exports
28+
- `src/errors.ts` - Error types and handling
29+
- `src/helpers.ts` - Utility functions for pagination
30+
- `src/type-utils.ts` - TypeScript type guards and utilities
31+
- `src/logging.ts` - Logging implementation
32+
33+
## Build and Validation
34+
35+
### Prerequisites
36+
37+
Always run these commands from the repository root:
38+
39+
```bash
40+
# Install dependencies first
41+
npm install
42+
```
43+
44+
### Build Process
45+
46+
```bash
47+
# Clean and build the project
48+
npm run build
49+
# This runs: rm -rf ./build && tsc
50+
```
51+
52+
### Validation Pipeline
53+
54+
The following checks must pass before any code changes:
55+
56+
1. **Linting** (required for CI):
57+
```bash
58+
npm run lint
59+
# Runs: prettier --check . && eslint . --ext .ts && cspell '**/*'
60+
```
61+
62+
2. **Tests** (required for CI):
63+
```bash
64+
npm test
65+
# Runs: jest ./test
66+
```
67+
68+
3. **Type Checking Examples** (CI also validates):
69+
```bash
70+
npm run examples:install # Install dependencies for all examples
71+
npm run examples:typecheck # Type-check all examples
72+
```
73+
74+
### CI/CD Pipeline
75+
76+
GitHub Actions runs on push/PR to main branch:
77+
- Tests on Node.js versions: 18.x, 19.x, 20.x, 22.x
78+
- Linting on all versions
79+
- Example type checking on Node.js 20.x
80+
81+
## Development Guidelines
82+
83+
### Code Style Requirements
84+
85+
- **NO semicolons** (enforced by Prettier)
86+
- **NO redundant code comments** - Only add comments for motivation/reasoning
87+
- **Comment length**: Max 80 characters, use multiline comments for longer text
88+
- **Import style**: CommonJS (`require`/`module.exports`)
89+
- **Avoid TypeScript escape hatches**: No `as any`, prefer type guards from `type-utils.ts`
90+
91+
### Making Changes
92+
93+
1. **Always build before testing**:
94+
```bash
95+
npm run build && npm test
96+
```
97+
98+
2. **For API endpoint changes**: Remember that `src/api-endpoints.ts` is generated. Changes to API endpoints must be made upstream.
99+
100+
3. **For new functionality**:
101+
- Add corresponding tests in `test/`
102+
- Export new types/functions from `src/index.ts`
103+
- Add type guards to `src/type-utils.ts` if working with API responses
104+
105+
4. **Error handling**: Use the error types from `src/errors.ts` and follow the existing patterns
106+
107+
### Publishing Prerequisites
108+
109+
Before publishing (handled by maintainers):
110+
```bash
111+
# Must be logged into npm
112+
npm whoami # Should not fail
113+
npm run prepublishOnly # Runs all checks
114+
```
115+
116+
## Project Structure
117+
118+
```
119+
notion-sdk-js/
120+
├── src/ # TypeScript source files
121+
│ ├── Client.ts # Main client class
122+
│ ├── api-endpoints.ts # ⚠️ GENERATED - DO NOT EDIT
123+
│ ├── errors.ts # Error types
124+
│ ├── helpers.ts # Pagination utilities
125+
│ ├── index.ts # Public exports
126+
│ └── type-utils.ts # Type guards
127+
├── test/ # Jest test files
128+
├── examples/ # Usage examples (each with own package.json)
129+
├── build/ # Compiled output (git-ignored)
130+
└── scripts/ # Build scripts
131+
```
132+
133+
## Common Issues and Solutions
134+
135+
1. **TypeScript version warning**: The project uses TypeScript 5.9.2 which may show warnings with ts-jest. This is expected and tests still pass.
136+
137+
2. **Build failures**: Always run `npm run clean` before `npm run build` if you encounter issues.
138+
139+
3. **Import errors**: This SDK uses CommonJS. Use `require()` not ES6 imports internally.
140+
141+
4. **Type errors**: Check `src/type-utils.ts` for existing type guards before creating new ones.
142+
143+
## Key Concepts
144+
145+
- **Pagination**: Use `iteratePaginatedAPI` or `collectPaginatedAPI` helpers from `src/helpers.ts`
146+
- **Type Guards**: Use `isFullPage`, `isFullBlock`, etc. from the public API
147+
- **Error Codes**: Compare against `APIErrorCode` and `ClientErrorCode` enums
148+
- **Logging**: Configurable via `LogLevel` enum in client options
149+
150+
## Final Note
151+
152+
Trust these instructions for common tasks. Only search the codebase if the information here is incomplete or incorrect. The patterns and practices documented here are consistently applied throughout the codebase.

0 commit comments

Comments
 (0)