Skip to content

Commit d7e1358

Browse files
kimyouknowkimyouknow
committed
chore: add cross-tool AI config files
Add AI assistant configuration for non-Claude Code tools: - AGENTS.md for OpenAI Codex CLI - .cursorrules for Cursor IDE - .github/copilot-instructions.md for GitHub Copilot
1 parent d02f912 commit d7e1358

3 files changed

Lines changed: 270 additions & 0 deletions

File tree

‎.cursorrules‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# react-simplikit Cursor Rules
2+
3+
## Project
4+
5+
React hooks/components library. Monorepo: `packages/core` + `packages/mobile`.
6+
7+
## Architecture
8+
9+
Unidirectional layers: `components → hooks → utils → _internal`
10+
Mobile depends on core. Core must NOT depend on mobile.
11+
12+
## Code Style
13+
14+
- `type` over `interface` for type aliases
15+
- Named functions in useEffect: `useEffect(function handleResize() { ... }, [])`
16+
- Named exports only, no default exports
17+
- No `any` — strict TypeScript
18+
- `.ts`/`.tsx` extensions in source imports (tsup converts to `.js`)
19+
- Strict boolean checks: `value !== undefined` not `if (value)`
20+
- Zero runtime dependencies
21+
- Always return cleanup in useEffect to remove listeners
22+
23+
## SSR-Safe Pattern
24+
25+
```ts
26+
const [state, setState] = useState(FIXED_INITIAL_VALUE);
27+
useEffect(function syncBrowserState() {
28+
if (isServer()) return;
29+
setState(getBrowserAPI());
30+
}, []);
31+
```
32+
33+
## Hook Returns
34+
35+
- 1 value → direct return
36+
- 2 values → tuple `[state, action]`
37+
- 3+ values → object `{ a, b, c }`
38+
39+
## Testing
40+
41+
- 100% coverage (Vitest)
42+
- SSR tests required for browser API hooks (`.ssr.test.ts`)
43+
- Use `renderHookSSR.serverOnly()` for SSR tests
44+
45+
## File Structure
46+
47+
Each hook in own folder: `src/hooks/useHookName/`
48+
49+
- `index.ts`, `useHookName.ts`, `useHookName.spec.ts` (core) / `.test.ts` (mobile), `useHookName.ssr.test.ts`
50+
- Docs: `useHookName.md` + `ko/useHookName.md`
51+
52+
## JSDoc
53+
54+
Required tags: `@description`, `@param`, `@returns`, `@example`
55+
56+
## Performance
57+
58+
- Throttle subscriptions at ~16ms (60fps)
59+
- Use `startTransition` for non-urgent state updates
60+
61+
## Commands
62+
63+
```bash
64+
yarn build # Build all (tsup)
65+
yarn test # Run tests (Vitest)
66+
yarn fix # Auto-fix lint + format
67+
yarn typecheck # Type check (tsc --noEmit)
68+
```
69+
70+
## Commits
71+
72+
Format: `<type>(<scope>): <description>`
73+
Types: feat, fix, docs, chore, refactor, test

‎.github/copilot-instructions.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Copilot Instructions for react-simplikit
2+
3+
## Quick Reference
4+
5+
- Monorepo: `packages/core` (react-simplikit) + `packages/mobile` (@react-simplikit/mobile)
6+
- Architecture: `components → hooks → utils → _internal` (unidirectional, no circular imports)
7+
- Mobile depends on core; core must NOT depend on mobile
8+
9+
## Code Style Rules
10+
11+
- Use `type` not `interface` for type aliases
12+
- Named functions in useEffect: `useEffect(function handleResize() { ... }, [])`
13+
- No default exports — named exports only
14+
- No `any` types — strict TypeScript
15+
- Use `.ts`/`.tsx` extensions in source imports (tsup converts to `.js`)
16+
- Strict boolean checks: `value !== undefined` not `if (value)`
17+
- Zero runtime dependencies
18+
- Always return cleanup in useEffect to remove listeners
19+
20+
## SSR-Safe Pattern (CRITICAL)
21+
22+
All browser API access must use this pattern:
23+
24+
```ts
25+
const [state, setState] = useState(FIXED_INITIAL_VALUE);
26+
useEffect(function syncBrowserState() {
27+
if (isServer()) return;
28+
setState(getBrowserAPI());
29+
}, []);
30+
```
31+
32+
Never call browser APIs during state initialization.
33+
34+
## Hook Return Values
35+
36+
- 1 value → return directly: `useDebounce<T>(value, delay): T`
37+
- 2 values → tuple: `useToggle(init): [boolean, () => void]`
38+
- 3+ values → object: `usePagination(): { page, nextPage, prevPage }`
39+
40+
## Testing
41+
42+
- 100% coverage required (Vitest)
43+
- SSR test required for browser API hooks:
44+
```ts
45+
import { renderHookSSR } from '../../_internal/test-utils/renderHookSSR.tsx';
46+
it('is safe on server side rendering', () => {
47+
const result = renderHookSSR.serverOnly(() => useHookName());
48+
expect(result.current).toBeDefined();
49+
});
50+
```
51+
52+
## JSDoc Template
53+
54+
Every public API requires:
55+
56+
````ts
57+
/**
58+
* @description Brief description of what it does
59+
* @param paramName - Parameter description
60+
* @returns What the hook/function returns
61+
* @example
62+
* ```ts
63+
* const value = useHookName(param);
64+
* ```
65+
*/
66+
````
67+
68+
## File Structure
69+
70+
```
71+
src/hooks/useHookName/
72+
├── index.ts # Re-export
73+
├── useHookName.ts # Implementation
74+
├── useHookName.spec.ts # Tests (core) / useHookName.test.ts (mobile)
75+
├── useHookName.ssr.test.ts # SSR tests
76+
├── useHookName.md # English docs
77+
└── ko/useHookName.md # Korean docs
78+
```
79+
80+
## Commands
81+
82+
```bash
83+
yarn build # Build all packages (tsup)
84+
yarn test # Run tests (Vitest)
85+
yarn fix # Auto-fix lint + format
86+
yarn typecheck # Type check (tsc --noEmit)
87+
```

‎AGENTS.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# AGENTS.md
2+
3+
> Tool-agnostic project conventions for AI coding assistants.
4+
> For Claude Code-specific instructions, see [CLAUDE.md](./CLAUDE.md).
5+
6+
## Project Overview
7+
8+
React utility hooks/components library. Monorepo with two packages:
9+
10+
- `react-simplikit` (`packages/core`) — Platform-independent React hooks & components
11+
- `@react-simplikit/mobile` (`packages/mobile`) — Mobile web utilities (viewport, keyboard, layout)
12+
13+
## Architecture
14+
15+
Layer dependency is **unidirectional** — no upward or circular imports:
16+
17+
```
18+
components → hooks → utils → _internal
19+
```
20+
21+
- Components may use hooks, utils, \_internal
22+
- Hooks may use utils, \_internal
23+
- Utils may use \_internal only
24+
- Mobile may depend on core; core must NOT depend on mobile
25+
26+
## File Structure
27+
28+
Each hook/component/util lives in its own folder with co-located docs:
29+
30+
```
31+
src/hooks/useHookName/
32+
├── index.ts # Re-export
33+
├── useHookName.ts # Implementation
34+
├── useHookName.spec.ts # Tests (core) / useHookName.test.ts (mobile)
35+
├── useHookName.ssr.test.ts # SSR safety tests
36+
├── useHookName.md # English docs
37+
└── ko/
38+
└── useHookName.md # Korean docs
39+
```
40+
41+
## Coding Standards
42+
43+
- **`type` over `interface`** — Always use `type` for type aliases
44+
- **Named functions in useEffect** — `useEffect(function handleResize() { ... }, [])` not arrow functions
45+
- **Strict boolean checks** — `value !== undefined` not `if (value)`
46+
- **Import extensions** — Use `.ts`/`.tsx` extensions in source imports (tsup converts to `.js` for ESM output)
47+
- **Named exports only** — No default exports
48+
- **No `any` types** — Full TypeScript strict mode
49+
- **Zero runtime dependencies**
50+
51+
### SSR-Safe Pattern
52+
53+
All hooks/utils accessing browser APIs must be SSR-safe:
54+
55+
```ts
56+
const [state, setState] = useState(FIXED_INITIAL_VALUE);
57+
useEffect(function syncBrowserState() {
58+
if (isServer()) return;
59+
setState(getBrowserAPI());
60+
}, []);
61+
```
62+
63+
Never initialize state with browser API calls (causes hydration mismatch).
64+
65+
### Hook Return Value Convention
66+
67+
- **Single value**: `useDebounce<T>(value, delay): T`
68+
- **Tuple** (2 items): `useToggle(init): [boolean, () => void]`
69+
- **Object** (3+ items): `usePagination(): { page, nextPage, prevPage }`
70+
71+
## Testing
72+
73+
- **100% coverage mandatory** — Enforced by Vitest coverage threshold
74+
- **SSR tests required** — All hooks accessing browser APIs need `.ssr.test.ts`
75+
- **useEffect cleanup** — Always return cleanup in useEffect to remove listeners
76+
- **SSR test pattern**:
77+
```ts
78+
import { renderHookSSR } from '../../_internal/test-utils/renderHookSSR.tsx';
79+
it('is safe on server side rendering', () => {
80+
const result = renderHookSSR.serverOnly(() => useHookName());
81+
expect(result.current).toBeDefined();
82+
});
83+
```
84+
85+
### Performance Patterns
86+
87+
- Throttle subscriptions at ~16ms (60fps)
88+
- Deduplicate to skip unchanged updates
89+
- Use `startTransition` for non-urgent state updates (React 18+)
90+
91+
## Documentation
92+
93+
- **Bilingual**: English + Korean (co-located in hook folders)
94+
- **JSDoc required**: Every public API must have `@description` + `@example` + `@param` + `@returns`
95+
96+
## Commit Convention
97+
98+
Format: `<type>(<scope>): <description>`
99+
100+
Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`
101+
Scope: `core`, `mobile`, or area name
102+
103+
## Commands
104+
105+
```bash
106+
yarn build # Build all packages (tsup)
107+
yarn test # Run tests (Vitest)
108+
yarn fix # Auto-fix lint + format
109+
yarn typecheck # Type check (tsc --noEmit)
110+
```

0 commit comments

Comments
 (0)