Skip to content

Commit 2d8b507

Browse files
Copilothi-ogawa
Copilot
and
hi-ogawa
committed
Add AGENTS.md files at root and packages/plugin-rsc
Co-authored-by: hi-ogawa <4232207+hi-ogawa@users.noreply.github.com>
1 parent 1a88245 commit 2d8b507

2 files changed

Lines changed: 311 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# AI Agent Development Guide
2+
3+
This document provides guidance for AI agents working with the vite-plugin-react monorepo.
4+
5+
## Repository Structure
6+
7+
This is a monorepo containing multiple Vite React plugins:
8+
9+
```
10+
packages/
11+
├── plugin-react/ # Main React plugin with Babel transformation
12+
├── plugin-react-swc/ # React plugin with SWC transformation
13+
├── plugin-react-oxc/ # Deprecated React plugin (merged with plugin-react)
14+
├── plugin-rsc/ # React Server Components plugin
15+
└── common/ # Shared utilities
16+
```
17+
18+
## Development Workflow
19+
20+
### Prerequisites
21+
22+
- Node.js ^20.19.0 || >=22.12.0
23+
- pnpm (package manager) - version 10.15.0
24+
25+
### Setup
26+
27+
```bash
28+
# Install dependencies
29+
pnpm install
30+
31+
# Build all packages
32+
pnpm build
33+
34+
# Start development mode (watch builds)
35+
pnpm dev
36+
```
37+
38+
### Key Commands
39+
40+
```bash
41+
# Linting
42+
pnpm lint # ESLint across all packages
43+
pnpm format # Prettier formatting
44+
45+
# Type checking
46+
pnpm typecheck # TypeScript checking
47+
48+
# Testing
49+
pnpm test # Run all tests
50+
pnpm test-unit # Unit tests only
51+
pnpm test-serve # Development server tests
52+
pnpm test-build # Build tests
53+
```
54+
55+
## Important Files
56+
57+
- `package.json` - Monorepo configuration and scripts
58+
- `pnpm-workspace.yaml` - Workspace configuration
59+
- `eslint.config.js` - ESLint configuration
60+
- `playground/` - Test applications for each plugin
61+
62+
## Plugin-Specific Notes
63+
64+
### @vitejs/plugin-react
65+
66+
- Located in `packages/plugin-react/`
67+
- Uses Babel for transformation
68+
- Primary React plugin for Vite
69+
70+
### @vitejs/plugin-react-swc
71+
72+
- Located in `packages/plugin-react-swc/`
73+
- Uses SWC for faster transformation
74+
- Alternative to Babel-based plugin
75+
76+
### @vitejs/plugin-rsc
77+
78+
- Located in `packages/plugin-rsc/`
79+
- Experimental React Server Components support
80+
- See [packages/plugin-rsc/AGENTS.md](packages/plugin-rsc/AGENTS.md) for detailed guidance
81+
82+
## Testing Guidelines
83+
84+
Each package has its own test suite. The playground directory contains integration tests that verify plugin functionality in realistic scenarios.
85+
86+
### Running Package-Specific Tests
87+
88+
```bash
89+
# Test specific package
90+
pnpm --filter ./packages/plugin-react test
91+
pnpm --filter ./packages/plugin-rsc test-e2e
92+
```
93+
94+
## Code Quality
95+
96+
- Code is automatically formatted with Prettier on commit
97+
- ESLint enforces code quality and consistency
98+
- TypeScript provides type safety
99+
- All packages require tests for new features
100+
101+
## Contributing
102+
103+
1. Follow the existing code style and patterns
104+
2. Add tests for new functionality
105+
3. Update documentation as needed
106+
4. Ensure all linting and tests pass
107+
5. Keep changes focused and atomic
108+
109+
## Common Tasks for AI Agents
110+
111+
### Adding a New Feature
112+
113+
1. Identify the appropriate package
114+
2. Read existing code patterns
115+
3. Add implementation with proper TypeScript types
116+
4. Add comprehensive tests
117+
5. Update relevant documentation
118+
119+
### Debugging Issues
120+
121+
1. Check playground tests for reproduction cases
122+
2. Use `pnpm dev` for live development
123+
3. Run specific test suites to isolate problems
124+
4. Review build outputs and error messages
125+
126+
### Performance Optimization
127+
128+
1. Profile with `vite-plugin-inspect`
129+
2. Analyze bundle sizes in playground builds
130+
3. Test with various React application patterns
131+
4. Ensure backward compatibility

‎packages/plugin-rsc/AGENTS.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# AI Agent Guide for @vitejs/plugin-rsc
2+
3+
This document provides specific guidance for AI agents working with the React Server Components (RSC) plugin.
4+
5+
## Overview
6+
7+
The `@vitejs/plugin-rsc` provides React Server Components support for Vite. It's built on the Vite environment API and enables:
8+
9+
- Framework-agnostic RSC bundler features
10+
- HMR support for both client and server components
11+
- CSS code-splitting and injection
12+
- Runtime-agnostic builds (works with various deployment targets)
13+
14+
## Key Concepts
15+
16+
### Environments
17+
18+
The plugin creates three distinct environments:
19+
20+
1. **rsc** - React server components rendering
21+
2. **ssr** - Server-side rendering environment
22+
3. **client** - Browser environment for hydration
23+
24+
### Architecture
25+
26+
```
27+
RSC Component → RSC Stream → SSR/Client Consumption → DOM/HTML
28+
```
29+
30+
See [Basic Concepts](README.md#basic-concepts) in the README for detailed flow diagrams.
31+
32+
## Development Workflow
33+
34+
### Setup
35+
36+
```bash
37+
# Build the plugin
38+
pnpm -C packages/plugin-rsc dev
39+
40+
# Type checking
41+
pnpm -C packages/plugin-rsc tsc-dev
42+
```
43+
44+
### Testing
45+
46+
```bash
47+
# Run all e2e tests
48+
pnpm -C packages/plugin-rsc test-e2e
49+
50+
# Run with UI (interactive filtering)
51+
pnpm -C packages/plugin-rsc test-e2e --ui
52+
53+
# Run specific test file
54+
pnpm -C packages/plugin-rsc test-e2e basic
55+
56+
# Run with grep filter
57+
pnpm -C packages/plugin-rsc test-e2e -g "hmr"
58+
```
59+
60+
### Examples
61+
62+
- `examples/starter/` - **Start here** - Comprehensive learning resource
63+
- `examples/basic/` - Advanced features and main e2e test suite
64+
- `examples/ssg/` - Static site generation example
65+
- `examples/react-router/` - React Router integration
66+
67+
## Important Files
68+
69+
### Core Plugin Files
70+
71+
- `src/plugin.ts` - Main plugin implementation
72+
- `src/environment/` - Environment-specific logic
73+
- `src/types/` - TypeScript definitions
74+
- `types/` - External type definitions
75+
76+
### Runtime APIs
77+
78+
- `rsc/` - Server component runtime
79+
- `ssr/` - SSR runtime
80+
- `browser/` - Client runtime
81+
- `vendor/` - Vendored react-server-dom
82+
83+
### Configuration
84+
85+
- `vite.config.ts` - Development configuration
86+
- `tsdown.config.ts` - Build configuration
87+
- `playwright.config.ts` - E2E test configuration
88+
89+
## Testing Patterns
90+
91+
### Test Fixture Patterns
92+
93+
1. **examples/basic** - Comprehensive test suite
94+
- Add test cases to `src/routes/`
95+
- Update routing in `src/routes/root.tsx`
96+
- Add tests to `e2e/basic.test.ts`
97+
98+
2. **setupInlineFixture** - Isolated edge case testing
99+
- Best for specific scenarios
100+
- See `e2e/ssr-thenable.test.ts` for pattern
101+
- Dependencies managed in `examples/e2e/package.json`
102+
103+
### Adding Tests
104+
105+
```bash
106+
# Create new test project (automatically runnable)
107+
pnpm -C packages/plugin-rsc/examples/e2e/temp/my-test dev
108+
```
109+
110+
## Common Development Tasks
111+
112+
### Adding New RSC Features
113+
114+
1. Understand the React Server Components specification
115+
2. Check existing implementation in `src/environment/`
116+
3. Add runtime support in appropriate environment
117+
4. Update type definitions
118+
5. Add comprehensive tests
119+
6. Update documentation
120+
121+
### Debugging Issues
122+
123+
1. Use `examples/starter` for basic reproduction
124+
2. Check environment-specific builds in `.vite/`
125+
3. Examine RSC streams and manifests
126+
4. Test across all three environments
127+
5. Verify HMR behavior
128+
129+
### Performance Optimization
130+
131+
1. Analyze bundle outputs with metadata plugins
132+
2. Check CSS code-splitting effectiveness
133+
3. Monitor RSC payload sizes
134+
4. Test streaming performance
135+
136+
## Key Plugin APIs
137+
138+
### Virtual Modules
139+
140+
- `virtual:vite-rsc/assets-manifest`
141+
- `virtual:vite-rsc/client-references`
142+
- `virtual:vite-rsc/server-references`
143+
- `virtual:vite-rsc/encryption-key`
144+
145+
### Environment Helper API
146+
147+
- `import.meta.viteRsc.loadCss()` - CSS loading
148+
- `?vite-rsc-css-export=<name>` - CSS exports
149+
150+
### Runtime Modules
151+
152+
- `@vitejs/plugin-rsc/rsc` - Server component rendering
153+
- `@vitejs/plugin-rsc/ssr` - SSR utilities
154+
- `@vitejs/plugin-rsc/browser` - Client-side RSC
155+
156+
## Best Practices
157+
158+
1. **Use setupInlineFixture for new tests** - More maintainable and faster
159+
2. **Follow existing patterns** - Check `examples/basic` for comprehensive examples
160+
3. **Test across environments** - Ensure functionality works in rsc, ssr, and client
161+
4. **Maintain backward compatibility** - RSC ecosystem is evolving rapidly
162+
5. **Document breaking changes** - Update CHANGELOG.md appropriately
163+
164+
## Troubleshooting
165+
166+
### Common Issues
167+
168+
1. **Module resolution errors** - Check `optimizeDeps.include` configuration
169+
2. **CSS not loading** - Verify `loadCss()` usage and environment setup
170+
3. **HMR not working** - Check component boundaries and environment isolation
171+
4. **Build failures** - Verify environment-specific configurations
172+
173+
### Debugging Tools
174+
175+
- Vite's built-in inspect plugin
176+
- Browser DevTools for client environment
177+
- Server logs for rsc/ssr environments
178+
- Playwright test inspector for e2e tests
179+
180+
For more detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

0 commit comments

Comments
 (0)