Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

CONTRIBUTING.md

161 lines8.4 KB

1# Contributing to TanStack AI
2​
3Thanks for contributing! This guide covers everything you need to get from a fresh clone to a merged PR.
4​
5## Prerequisites
6​
7- **pnpm**: 10.17.0 or newer. Use the version pinned in `packageManager` (`pnpm@11.1.1`).
8 - Recommended: install via [Corepack](https://nodejs.org/api/corepack.html). Run `corepack enable` once and pnpm is managed automatically.
9- **Git**.
10​
11## Initial setup
12​
13```bash
14git clone https://github.com/TanStack/ai.git
15cd ai
16pnpm install
17pnpm run build:all # build all public packages once so workspace deps resolve
18```
19​
20`pnpm install` runs Playwright's chromium download (used by the E2E suite). If you don't need E2E, you can skip it via `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 pnpm install`.
21​
22## Repository layout
23​
24```
25packages/typescript/ # Public, published packages (@tanstack/ai, @tanstack/ai-openai, etc.)
26testing/ # Internal test harnesses — NOT published
27 e2e/ # Playwright + aimock E2E suite (mandatory coverage for all changes)
28 panel/ # Stream processor visualisation panel
29examples/ # Example apps (React, Solid, Vue, Svelte, PHP, Python, vanilla)
30codemods/ # Internal codemods (not published)
31docs/ # Documentation source
32scripts/ # Repo-level scripts (doc generation, model sync, link verification)
33```
34​
35- Direct children of `packages/typescript/` are public packages (published to npm).
36- Everything under `examples/`, `testing/`, and `codemods/` is `"private": true` and excluded from build/publish.
37- The build system is **Nx** with affected-target detection.
38- The package manager is **pnpm** with workspace + catalog protocols.
39​
40For deeper architecture details (adapter system, isomorphic tools, framework integrations), see `CLAUDE.md` at the repo root.
41​
42## Day-to-day commands
43​
44All commands are run from the repo root. Nx handles affected detection and caching.
45​
46| Goal | Command |
47| ----------------------------- | ------------------- |
48| Run unit tests (affected) | `pnpm test:lib` |
49| Watch unit tests | `pnpm test:lib:dev` |
50| Type-check (affected) | `pnpm test:types` |
51| Lint (affected) | `pnpm test:eslint` |
52| Verify build artifacts | `pnpm test:build` |
53| Format the repo | `pnpm format` |
54| Build (affected) | `pnpm build` |
55| Build everything | `pnpm build:all` |
56| Run the full CI suite locally | `pnpm test` |
57| Run the affected-PR check | `pnpm test:pr` |
58| E2E suite | `pnpm test:e2e` |
59| E2E with Playwright UI | `pnpm test:e2e:ui` |
60​
61Working on a single package? `cd packages/typescript/<pkg>` and use its scripts directly (`pnpm test:lib`, `pnpm test:types`, etc.).
62​
63## TypeScript configuration
64​
65There is a single `tsconfig.base.json` at the repo root with the shared `compilerOptions`. Every package extends it and overrides only what's unique to that package (e.g. `outDir`, JSX runtime, framework lib).
66​
67The standardised per-package shape is:
68​
69```jsonc
71 "extends": "../../../tsconfig.base.json",
72 "compilerOptions": {
73 "outDir": "dist",
74 // + package-specific overrides only
75 },
76 "include": ["src", "tests"],
77 "exclude": ["node_modules", "dist"],
79```
80​
81Tests are included in typecheck. `vite.config.ts` / `vitest.config.ts` are not — they're tooling configs typechecked by the build tools themselves.
82​
83## Adding a unit test
84​
85- Place tests under `packages/typescript/<pkg>/tests/` with the suffix `.test.ts` (or `.test.tsx` for JSX).
86- Vitest's defaults discover anything matching `**/*.{test,spec}.?(c|m)[jt]s?(x)` — no per-package config is needed.
87- Tests are typechecked by `tsc` and linted by ESLint.
88​
89## Adding E2E test coverage (required)
90​
91**Every feature, bug fix, or behaviour change MUST have E2E coverage.** See `testing/e2e/README.md` for the full guide. Quick reference:
92​
93| Change type | What to add |
94| -------------------------------------- | ------------------------------------------------------------------------ |
95| New provider adapter | Add provider to `feature-support.ts` + `test-matrix.ts`. Tests auto-run. |
96| New feature (e.g. new generation type) | Add to types, feature config, support matrix, fixture, spec file. |
97| Chat / streaming bug fix | Test case in `chat.spec.ts` or `tools-test/`. |
98| Tool system change | Scenario in `tools-test-scenarios.ts` + spec. |
99| Middleware change | Test in `middleware.spec.ts`. |
100| Client-side change (useChat etc.) | Test covering the observable behavior change. |
101​
102Run the suite locally with `pnpm test:e2e`. Record real LLM fixtures with `OPENAI_API_KEY=sk-... pnpm --filter @tanstack/ai-e2e record`.
103​
104## Changesets
105​
106Any change that ships in a published package requires a changeset. Examples, internal test harnesses, codemods, and docs do not.
107​
108```bash
109pnpm changeset
110```
111​
112Pick the affected packages and the bump type:
113​
114- **patch**: bug fix, internal refactor, perf, docs in package, no API change.
115- **minor**: new public API, new opt-in behaviour, backwards-compatible enhancement.
116- **major**: breaking change to a published API surface. Coordinate with maintainers first.
117​
118The defensive `ignore` list in `.changeset/config.json` blocks accidental publication from examples/testing/codemods even if `"private": true` is ever dropped.
119​
120## Branches and commits
121​
122- Branch off `main`. Name the branch after the change (`fix/openai-streaming-eof`, `feat/anthropic-cache-control`).
123- Conventional Commits aren't strictly enforced, but follow the prefixes you see in `git log`: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `ci:`.
124- Keep commits logical. The repo prefers a few coherent commits over one giant squash.
125​
126## Pull request flow
127​
1281. Push your branch and open a PR against `main`.
1292. CI runs: `pnpm test:pr` (sherif workspace check, knip dead-code, docs link verification, ESLint, unit tests, typecheck, build artifacts, build) + the full E2E suite.
1303. Address review comments.
1314. A maintainer merges. Releases are cut via Changesets — your changeset entry lands in the next release.
132​
133The PR template lists the steps. The `Test plan` section is required — describe how a reviewer can verify your change.
134​
135## Adding a new provider adapter
136​
137The pattern lives in `packages/typescript/ai-openai/`, `packages/typescript/ai-anthropic/`, `packages/typescript/ai-gemini/`, etc. New core adapters typically:
138​
1391. Create `packages/typescript/ai-<provider>/` with `package.json`, `tsconfig.json`, `src/`, `tests/`, `README.md`. Copy structure from an existing adapter.
1402. Implement tree-shakeable adapter exports under `src/adapters/` (`text.ts`, `embed.ts`, `summarize.ts`, etc.).
1413. Add `model-meta.ts` so per-model type safety works.
1424. Wire the provider into `testing/e2e/feature-support.ts` and `testing/e2e/test-matrix.ts`. Existing provider-coverage tests pick it up automatically.
1435. Record fixtures (`OPENAI_API_KEY=... pnpm --filter @tanstack/ai-e2e record`) — or write deterministic ones by hand. **No real API keys at test time.**
1446. Add a `pnpm changeset` entry.
145​
146If you're building a community/third-party adapter that lives outside this repo, follow `docs/community-adapters/guide.md` instead.
147​
148## Known gaps
149​
150- **Vue/Svelte SFCs are not currently linted.** Our linter doesn't yet support `.vue`/`.svelte` parsers in the toolchain we use; the script blocks inside those files rely on TypeScript and tests for safety. If you're touching a `.svelte` or `.vue` file, lean on `tsc` / `svelte-check` / `vue-tsc` and explicit tests.
151- **Build configs (`vite.config.ts`, `vitest.config.ts`) are not in the `tsc` typecheck pass.** They're typechecked at build time by vite/vitest themselves. If you make changes there, run `pnpm build` or `pnpm test:lib` to surface issues.
152​
153## Reporting issues / getting help
154​
155- Bugs: open a GitHub issue with a minimal repro (the bug report template in `.github/issue_template/bug_report.yml` walks you through it).
156- Questions / discussions: [TanStack Discord](https://tlinz.com/discord).
157- Security: follow the disclosure process in `SECURITY.md` (if applicable) or email the maintainers directly.
158​
159## Code of Conduct
160​
161By participating you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md).