+
+)}>
+ {error.message}
+ ++## 🤖 AI-Friendly Documentation + +Suspensive provides comprehensive AI-friendly documentation to help AI assistants understand and work with the codebase effectively: + +- **[.cursorrules](./.cursorrules)** - Complete project overview and development guidelines for AI assistants +- **[.github/copilot/instructions.md](./.github/copilot/instructions.md)** - GitHub Copilot-specific instructions and patterns +- **[AI_DEVELOPMENT_GUIDE.md](./AI_DEVELOPMENT_GUIDE.md)** - Quick reference guide for AI tools + +These resources help AI assistants: +- Understand the monorepo structure and package relationships +- Follow consistent code patterns and conventions +- Navigate the development workflow +- Make contextually appropriate suggestions +- Maintain code quality and SSR compatibility + +
+ ## Contributors Read our [Contributing Guide](./CONTRIBUTING.md) to familiarize yourself with Suspensive's development process, how to suggest bug fixes and improvements, and the steps for building and testing your changes. From 754f56f943dd89911a0107bf86257cd93085b322 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 12 Nov 2025 06:40:13 +0000 Subject: [PATCH 3/4] docs: add package-level AI context files Co-authored-by: manudeli <61593290+manudeli@users.noreply.github.com> --- docs/suspensive.org/.ai-context.md | 186 ++++++++++++++++++++++++++++ packages/react-dom/.ai-context.md | 92 ++++++++++++++ packages/react-query/.ai-context.md | 123 ++++++++++++++++++ packages/react/.ai-context.md | 90 ++++++++++++++ 4 files changed, 491 insertions(+) create mode 100644 docs/suspensive.org/.ai-context.md create mode 100644 packages/react-dom/.ai-context.md create mode 100644 packages/react-query/.ai-context.md create mode 100644 packages/react/.ai-context.md diff --git a/docs/suspensive.org/.ai-context.md b/docs/suspensive.org/.ai-context.md new file mode 100644 index 000000000..f4cf05d73 --- /dev/null +++ b/docs/suspensive.org/.ai-context.md @@ -0,0 +1,186 @@ +# Documentation Site - AI Context + +## Site Purpose +Official documentation website for Suspensive libraries. Built with Next.js and Nextra for a modern, searchable documentation experience. + +## Tech Stack +- **Framework**: Next.js 15 (App Router) +- **Documentation**: Nextra (MDX-based) +- **Styling**: Tailwind CSS +- **Search**: Pagefind +- **i18n**: Built-in Next.js internationalization + +## Directory Structure + +``` +docs/suspensive.org/ +├── src/ +│ ├── app/ # Next.js app directory +│ │ └── [lang]/ # Language-specific routes +│ ├── content/ # MDX documentation files +│ │ ├── en/ # English documentation +│ │ │ └── docs/ # Organized by package +│ │ └── ko/ # Korean documentation +│ │ └── docs/ +│ ├── components/ # React components for docs +│ └── utils/ # Utility functions +├── public/ # Static assets +└── next.config.mjs # Next.js configuration +``` + +## Content Structure + +Documentation is organized by package: +- `/docs/react/` - @suspensive/react docs +- `/docs/react-query/` - @suspensive/react-query docs +- `/docs/react-dom/` - @suspensive/react-dom docs +- `/docs/codemods/` - @suspensive/codemods docs +- etc. + +Each section includes: +- `installation.mdx` - Installation guide +- `motivation.mdx` - Why the package exists +- Component/hook documentation files +- `migration/` - Migration guides + +## Languages + +- **English** (`/en/`): Primary language +- **Korean** (`/ko/`): Secondary language + +When updating docs: +1. Update English version first +2. Update Korean version with equivalent content +3. Maintain same file structure in both languages + +## MDX Features + +### Code Blocks +```tsx +// Syntax highlighting with tsx/typescript/javascript +
: Loading...
+ }
+{data.name}
// data is always defined
+}
+```
+
+### Parallel Queries
+```typescript
+const [users, posts] = useSuspenseQueries({
+ queries: [
+ { queryKey: ['users'], queryFn: fetchUsers },
+ { queryKey: ['posts'], queryFn: fetchPosts }
+ ]
+})
+```
+
+## Type Safety
+All hooks maintain full type inference from TanStack Query while guaranteeing non-undefined data.
diff --git a/packages/react/.ai-context.md b/packages/react/.ai-context.md
new file mode 100644
index 000000000..7694b544b
--- /dev/null
+++ b/packages/react/.ai-context.md
@@ -0,0 +1,90 @@
+# @suspensive/react - AI Context
+
+## Package Purpose
+Core React Suspense utilities that make React Suspense easier to use. This package provides SSR-safe components and simplified error boundaries.
+
+## Key Components
+
+### `
@@ -83,6 +88,7 @@ export const useMyHook = (initialValue: T) => {
## Common Commands by Package
Each package supports:
+
- `build`: Build the package
- `ci:eslint`: Lint
- `ci:test`: Run tests
@@ -108,21 +114,25 @@ Each package supports:
## Package-Specific Notes
### @suspensive/react
+
- Core package, no external dependencies
- Must work in SSR and CSR environments
- Focus on declarative APIs
### @suspensive/react-query
+
- Auto-detects TanStack Query version (v4 or v5)
- Wraps around react-query-4 and react-query-5 packages
- Includes CLI tools for version management
### @suspensive/react-dom
+
- Browser-only utilities
- Uses Intersection Observer API
- Handles viewport-based interactions
### Documentation Site
+
- Built with Next.js 15 and Nextra
- Supports i18n (English and Korean)
- Uses Tailwind CSS for styling
@@ -130,7 +140,9 @@ Each package supports:
## Useful Patterns in Codebase
### Wrapping Components
+
The library uses a pattern of wrapping React components to add functionality:
+
```typescript
- Important note here
-
+Important note here
```
### Nextra Features
+
- Automatic table of contents
- File-based routing
- Built-in search
@@ -96,24 +103,28 @@ pnpm run start
## Writing Documentation Guidelines
### 1. Structure
+
- Use clear headings (##, ###)
- Include code examples for all APIs
- Add "Why?" sections to explain motivation
- Include common use cases
### 2. Code Examples
+
- Show realistic use cases
- Include imports
- Add comments for complex code
- Demonstrate both simple and advanced usage
### 3. API Documentation
+
- List all props/parameters
- Specify types
- Mark required vs optional
- Include default values
### 4. Links
+
- Link to related documentation
- Link to external resources (React docs, TanStack Query docs)
- Use relative links for internal pages
@@ -121,6 +132,7 @@ pnpm run start
## Common Patterns
### API Documentation Page
+
```mdx
# ComponentName
@@ -136,16 +148,18 @@ Basic usage example...
## Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| prop1 | string | Yes | - | What it does |
+| Prop | Type | Required | Default | Description |
+| ----- | ------ | -------- | ------- | ------------ |
+| prop1 | string | Yes | - | What it does |
## Examples
### Basic Example
+
Code example...
### Advanced Example
+
More complex example...
```
@@ -159,6 +173,7 @@ More complex example...
## Deployment
Documentation is deployed via GitHub Actions:
+
- On push to main branch
- Deploys to suspensive.org
- Automatically runs build and deploy
@@ -166,6 +181,7 @@ Documentation is deployed via GitHub Actions:
## Search
Pagefind provides client-side search:
+
- Runs after build
- Indexes all documentation pages
- Supports multiple languages
diff --git a/packages/react-dom/.ai-context.md b/packages/react-dom/.ai-context.md
index 54fcd9e7a..c0ec8e587 100644
--- a/packages/react-dom/.ai-context.md
+++ b/packages/react-dom/.ai-context.md
@@ -1,11 +1,13 @@
# @suspensive/react-dom - AI Context
## Package Purpose
+
DOM-specific utilities that leverage browser APIs like Intersection Observer. Browser-only features that work with React Suspense patterns.
## Key Components
### `` for SSR apps
- Uses Intersection Observer API (requires polyfill for older browsers)
@@ -47,6 +52,7 @@ Fade-in animation when component enters viewport.
## Common Patterns
### With SSR Safety
+
```typescript
import { ClientOnly } from '@suspensive/react'
import { InView } from '@suspensive/react-dom'
@@ -59,15 +65,17 @@ import { InView } from '@suspensive/react-dom'
```
### Lazy Loading Images
+
```typescript
- {({ inView }) =>
+ {({ inView }) =>
inView ? :
```
### Tracking Visibility
+
```typescript
const [isVisible, setIsVisible] = useState(false)
@@ -77,16 +85,19 @@ const [isVisible, setIsVisible] = useState(false)
```
## File Structure
+
- `src/InView.tsx` - InView component
- `src/FadeIn.tsx` - FadeIn component
- Tests co-located with components
## Browser Compatibility
+
- Modern browsers with Intersection Observer support
- For older browsers, requires Intersection Observer polyfill
- Falls back gracefully when API not available
## Performance Considerations
+
- Uses passive observers for scroll performance
- Automatically disconnects observers when unmounted
- Efficient for tracking multiple elements
diff --git a/packages/react-query/.ai-context.md b/packages/react-query/.ai-context.md
index a83350a75..ad502b51d 100644
--- a/packages/react-query/.ai-context.md
+++ b/packages/react-query/.ai-context.md
@@ -1,9 +1,11 @@
# @suspensive/react-query - AI Context
## Package Purpose
+
Integration layer for @tanstack/react-query that provides Suspense-enabled hooks and components. Auto-detects and supports both v4 and v5 of TanStack Query.
## Key Features
+
- Suspense-enabled query hooks (data is never undefined)
- Auto-detection of TanStack Query version (v4 or v5)
- CLI tool for version management
@@ -12,42 +14,50 @@ Integration layer for @tanstack/react-query that provides Suspense-enabled hooks
## Key Hooks
### `useSuspenseQuery()`
+
Suspense-enabled version of useQuery. Data is always defined.
+
```typescript
const { data } = useSuspenseQuery({
queryKey: ['user', id],
- queryFn: () => fetchUser(id)
+ queryFn: () => fetchUser(id),
})
// data is UserType, not UserType | undefined
```
### `useSuspenseQueries()`
+
Suspense-enabled version of useQueries.
+
```typescript
const [query1, query2] = useSuspenseQueries({
queries: [
{ queryKey: ['user', 1], queryFn: fetchUser },
- { queryKey: ['posts'], queryFn: fetchPosts }
- ]
+ { queryKey: ['posts'], queryFn: fetchPosts },
+ ],
})
// Both query1.data and query2.data are always defined
```
### `useSuspenseInfiniteQuery()`
+
Suspense-enabled version of useInfiniteQuery.
+
```typescript
const { data, fetchNextPage } = useSuspenseInfiniteQuery({
queryKey: ['posts'],
queryFn: ({ pageParam }) => fetchPosts(pageParam),
initialPageParam: 0,
- getNextPageParam: (lastPage) => lastPage.nextCursor
+ getNextPageParam: (lastPage) => lastPage.nextCursor,
})
```
## Components
### `
{({ data }) =>
@@ -31,7 +38,9 @@ Group multiple error boundaries for coordinated reset.
```
### `
: Loading...
}