Skip to content

Commit 98117a9

Browse files
isekovanicisekovanic
committed
chore: add AGENTS.md file
1 parent 503e9c8 commit 98117a9

File tree

2 files changed

+191
-0
lines changed

2 files changed

+191
-0
lines changed

‎AGENTS.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Guidance for AI coding agents
2+
3+
File purpose: operational rules for automated or assisted code changes. Human-facing conceptual docs belong in `README.md` or the docs site.
4+
5+
## Repository purpose
6+
7+
Stream Chat SDKs for:
8+
9+
- React Native CLI
10+
- Expo
11+
12+
Goals: API stability, backward compatibility, predictable releases, strong test coverage, accessibility, and performance discipline.
13+
14+
## Tech & toolchain
15+
16+
- Languages: TypeScript, React (web + native)
17+
- Runtime: Node (use `nvm use` with `.nvmrc`)
18+
- Package manager: Yarn (V1)
19+
- Testing: Jest (unit)
20+
- Lint/Format: ESLint + Prettier
21+
- Build: Package-local build scripts (composed via root)
22+
- Release: Conventional Commits -> automated versioning/publishing
23+
- Platforms:
24+
- React Native: iOS and Android
25+
26+
## Environment setup
27+
28+
1. `nvm use`
29+
2. `yarn install`
30+
3. (Optional) Verify: `node -v` matches `.nvmrc`
31+
4. `cd package`
32+
5. `yarn install-all && cd ..`
33+
6. Run tests: `yarn test:unit`
34+
35+
## Project layout (high-level)
36+
37+
- `package/`
38+
- `native-package/` (`react-native` CLI specific bundle)
39+
- `expo-package/` (`Expo` specific bundle)
40+
- `.` (core UI SDK, shared between both bundles)
41+
- `examples/`
42+
- `ExpoMessaging/`
43+
- `SampleApp/`
44+
- `TypeScriptMessaging/`
45+
- Config roots: linting, tsconfig, playwright, babel
46+
- Do not edit generated output (`lib/`, build artifacts)
47+
48+
## Core commands (Runbook)
49+
50+
| Action | Command |
51+
|-------------------------|------------------------------|
52+
| Install deps | `yarn install` |
53+
| Full build | `yarn install-all` |
54+
| Watch (if available) | `yarn start` (add if absent) |
55+
| Lint | `yarn lint` |
56+
| Fix lint (if separate) | `yarn lint --fix` |
57+
| Unit tests (CI profile) | `yarn test:ci:all` |
58+
59+
## API design principles
60+
61+
- Semantic versioning
62+
- Use `@deprecated` JSDoc with replacement guidance
63+
- Provide migration docs for breaking changes
64+
- Avoid breaking changes; prefer additive evolution
65+
- Public surfaces: explicit TypeScript types/interfaces
66+
- Consistent naming: `camelCase` for functions/properties, `PascalCase` for components/types
67+
68+
### Deprecation lifecycle
69+
70+
1. Mark with `@deprecated` + rationale + alternative.
71+
2. Maintain for at least one minor release unless security-critical.
72+
3. Add to migration documentation.
73+
4. Remove only in next major.
74+
75+
## Performance guidelines
76+
77+
- Minimize re-renders (memoization, stable refs)
78+
- Use `React.memo` / `useCallback` / `useMemo` when profiling justifies
79+
- Clean up side effects (`AbortController` for network calls, unsubscribe listeners when unmounting)
80+
- Monitor bundle size; justify increases > 2% per package
81+
- Prefer lazy loading for optional heavy modules
82+
- Avoid unnecessary large dependency additions
83+
84+
## Accessibility (a11y)
85+
86+
- All interactive elements keyboard accessible
87+
- Provide ARIA roles/labels where semantic tags insufficient
88+
- Maintain color contrast (WCAG AA)
89+
- Do not convey state by color alone
90+
- Announce dynamic content changes (ARIA live regions if needed)
91+
92+
## Error & logging policy
93+
94+
- Public API: throw descriptive errors or return typed error results (consistent with existing patterns)
95+
- No console noise in production builds
96+
- Internal debug logging gated behind env flag (if present)
97+
- Never leak credentials/user data in errors
98+
99+
## Concurrency & async
100+
101+
- Cancel stale async operations (media, network) when components unmount
102+
- Use `AbortController` for fetch-like APIs
103+
- Avoid race conditions: check instance IDs / timestamps before state updates
104+
105+
## Testing strategy
106+
107+
- Unit: pure functions, small components
108+
- React Native: target minimal smoke + platform logic (avoid flakiness)
109+
- Mocks/fakes: prefer shared test helpers
110+
- Coverage target: maintain or improve existing percentage (fail PR if global coverage drops)
111+
- File naming: `*.test.ts` / `*.spec.ts(x)`
112+
- Add tests for: new public API, bug fixes (regression test), performance-sensitive utilities
113+
114+
## CI expectations
115+
116+
- Mandatory: build, lint, type check, unit/integration tests, (optionally) E2E smoke
117+
- Node versions: those listed in matrix (see workflow YAML)
118+
- Failing or flaky tests: fix or quarantine with justification PR comment (temporary)
119+
- Zero new warnings
120+
121+
## Release workflow (high-level)
122+
123+
1. Conventional Commit messages on PR merge
124+
2. Release automation aggregates commits
125+
3. Version bump + changelog + tag
126+
4. Publish to registry
127+
5. Deprecations noted in CHANGELOG
128+
6. Ensure docs updated prior to publishing breaking changes
129+
130+
## Dependency policy
131+
132+
- Avoid adding large deps without justification (size, maintenance)
133+
- Prefer existing utility packages
134+
- Run `yarn audit` (or equivalent) if adding security-impacting deps
135+
- Keep upgrades separate from feature changes when possible
136+
137+
## Samples & docs
138+
139+
- New public feature: update at least one sample app
140+
- Breaking changes: provide migration snippet
141+
- Keep code snippets compilable
142+
- Use placeholder keys (`YOUR_STREAM_KEY`)
143+
144+
## React Native specifics
145+
146+
- Clear Metro cache if module resolution has issues: `yarn react-native start --reset-cache` (for RN CLI) or `yarn expo start --dev-client -c` (for `Expo`)
147+
- Test on iOS + Android for native module or platform-specific UI changes
148+
- Avoid unguarded web-only APIs in shared code
149+
150+
## Linting & formatting
151+
152+
- Run `yarn lint` before commit
153+
- Narrowly scope `eslint-disable` with inline comments and rationale
154+
- No broad rule disabling
155+
156+
## Commit / PR conventions
157+
158+
- Small, focused PRs
159+
- Include tests for changes
160+
- Screenshot or video for UI changes (before/after)
161+
- Label breaking changes clearly in description
162+
- Document public API changes
163+
164+
## Security
165+
166+
- No credentials or real user data
167+
- Use placeholders in examples
168+
- Scripts must error on missing critical env vars
169+
- Avoid introducing unmaintained dependencies
170+
171+
## Prohibited edits
172+
173+
- Do not edit build artifacts (`lib/`, generated types where present)
174+
- Do not bypass lint/type errors with force merges
175+
176+
## Quick agent checklist (per commit)
177+
178+
- Build succeeds
179+
- Lint clean
180+
- Type check clean
181+
- Tests (unit/integration) green
182+
- Coverage not reduced
183+
- Public API docs updated if changed
184+
- Samples updated if feature surfaced
185+
- No new warnings
186+
- No generated files modified
187+
188+
---
189+
190+
Refine this file iteratively for agent clarity; keep human-facing explanations in docs site / `README.md`.

‎package/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"README.md"
2323
],
2424
"scripts": {
25+
"install-all": "(yarn install --force && (cd native-package && yarn install --force) && (cd expo-package && yarn install --force))",
2526
"build": "rimraf lib && yarn run --silent build-translations && bob build && yarn run --silent copy-translations",
2627
"build-translations": "i18next",
2728
"copy-translations": "echo '\u001b[34mℹ\u001b[0m Copying translation files to \u001b[34mlib/typescript/i18n\u001b[0m' && cp -R -f ./src/i18n ./lib/typescript/i18n && echo '\u001b[32m✓\u001b[0m Done Copying Translations'",

0 commit comments

Comments
 (0)