From 1a88245cae4779925b508b3f411f1b922446160c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 7 Sep 2025 07:33:09 +0000 Subject: [PATCH 1/4] Initial plan From 2d8b507c1a44c4ae2cfff97311984ef47fe0fb40 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 7 Sep 2025 07:37:29 +0000 Subject: [PATCH 2/4] Add AGENTS.md files at root and packages/plugin-rsc Co-authored-by: hi-ogawa <4232207+hi-ogawa@users.noreply.github.com> --- AGENTS.md | 131 +++++++++++++++++++++++++ packages/plugin-rsc/AGENTS.md | 180 ++++++++++++++++++++++++++++++++++ 2 files changed, 311 insertions(+) create mode 100644 AGENTS.md create mode 100644 packages/plugin-rsc/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..f81080d5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,131 @@ +# AI Agent Development Guide + +This document provides guidance for AI agents working with the vite-plugin-react monorepo. + +## Repository Structure + +This is a monorepo containing multiple Vite React plugins: + +``` +packages/ +├── plugin-react/ # Main React plugin with Babel transformation +├── plugin-react-swc/ # React plugin with SWC transformation +├── plugin-react-oxc/ # Deprecated React plugin (merged with plugin-react) +├── plugin-rsc/ # React Server Components plugin +└── common/ # Shared utilities +``` + +## Development Workflow + +### Prerequisites + +- Node.js ^20.19.0 || >=22.12.0 +- pnpm (package manager) - version 10.15.0 + +### Setup + +```bash +# Install dependencies +pnpm install + +# Build all packages +pnpm build + +# Start development mode (watch builds) +pnpm dev +``` + +### Key Commands + +```bash +# Linting +pnpm lint # ESLint across all packages +pnpm format # Prettier formatting + +# Type checking +pnpm typecheck # TypeScript checking + +# Testing +pnpm test # Run all tests +pnpm test-unit # Unit tests only +pnpm test-serve # Development server tests +pnpm test-build # Build tests +``` + +## Important Files + +- `package.json` - Monorepo configuration and scripts +- `pnpm-workspace.yaml` - Workspace configuration +- `eslint.config.js` - ESLint configuration +- `playground/` - Test applications for each plugin + +## Plugin-Specific Notes + +### @vitejs/plugin-react + +- Located in `packages/plugin-react/` +- Uses Babel for transformation +- Primary React plugin for Vite + +### @vitejs/plugin-react-swc + +- Located in `packages/plugin-react-swc/` +- Uses SWC for faster transformation +- Alternative to Babel-based plugin + +### @vitejs/plugin-rsc + +- Located in `packages/plugin-rsc/` +- Experimental React Server Components support +- See [packages/plugin-rsc/AGENTS.md](packages/plugin-rsc/AGENTS.md) for detailed guidance + +## Testing Guidelines + +Each package has its own test suite. The playground directory contains integration tests that verify plugin functionality in realistic scenarios. + +### Running Package-Specific Tests + +```bash +# Test specific package +pnpm --filter ./packages/plugin-react test +pnpm --filter ./packages/plugin-rsc test-e2e +``` + +## Code Quality + +- Code is automatically formatted with Prettier on commit +- ESLint enforces code quality and consistency +- TypeScript provides type safety +- All packages require tests for new features + +## Contributing + +1. Follow the existing code style and patterns +2. Add tests for new functionality +3. Update documentation as needed +4. Ensure all linting and tests pass +5. Keep changes focused and atomic + +## Common Tasks for AI Agents + +### Adding a New Feature + +1. Identify the appropriate package +2. Read existing code patterns +3. Add implementation with proper TypeScript types +4. Add comprehensive tests +5. Update relevant documentation + +### Debugging Issues + +1. Check playground tests for reproduction cases +2. Use `pnpm dev` for live development +3. Run specific test suites to isolate problems +4. Review build outputs and error messages + +### Performance Optimization + +1. Profile with `vite-plugin-inspect` +2. Analyze bundle sizes in playground builds +3. Test with various React application patterns +4. Ensure backward compatibility diff --git a/packages/plugin-rsc/AGENTS.md b/packages/plugin-rsc/AGENTS.md new file mode 100644 index 00000000..f65c19cd --- /dev/null +++ b/packages/plugin-rsc/AGENTS.md @@ -0,0 +1,180 @@ +# AI Agent Guide for @vitejs/plugin-rsc + +This document provides specific guidance for AI agents working with the React Server Components (RSC) plugin. + +## Overview + +The `@vitejs/plugin-rsc` provides React Server Components support for Vite. It's built on the Vite environment API and enables: + +- Framework-agnostic RSC bundler features +- HMR support for both client and server components +- CSS code-splitting and injection +- Runtime-agnostic builds (works with various deployment targets) + +## Key Concepts + +### Environments + +The plugin creates three distinct environments: + +1. **rsc** - React server components rendering +2. **ssr** - Server-side rendering environment +3. **client** - Browser environment for hydration + +### Architecture + +``` +RSC Component → RSC Stream → SSR/Client Consumption → DOM/HTML +``` + +See [Basic Concepts](README.md#basic-concepts) in the README for detailed flow diagrams. + +## Development Workflow + +### Setup + +```bash +# Build the plugin +pnpm -C packages/plugin-rsc dev + +# Type checking +pnpm -C packages/plugin-rsc tsc-dev +``` + +### Testing + +```bash +# Run all e2e tests +pnpm -C packages/plugin-rsc test-e2e + +# Run with UI (interactive filtering) +pnpm -C packages/plugin-rsc test-e2e --ui + +# Run specific test file +pnpm -C packages/plugin-rsc test-e2e basic + +# Run with grep filter +pnpm -C packages/plugin-rsc test-e2e -g "hmr" +``` + +### Examples + +- `examples/starter/` - **Start here** - Comprehensive learning resource +- `examples/basic/` - Advanced features and main e2e test suite +- `examples/ssg/` - Static site generation example +- `examples/react-router/` - React Router integration + +## Important Files + +### Core Plugin Files + +- `src/plugin.ts` - Main plugin implementation +- `src/environment/` - Environment-specific logic +- `src/types/` - TypeScript definitions +- `types/` - External type definitions + +### Runtime APIs + +- `rsc/` - Server component runtime +- `ssr/` - SSR runtime +- `browser/` - Client runtime +- `vendor/` - Vendored react-server-dom + +### Configuration + +- `vite.config.ts` - Development configuration +- `tsdown.config.ts` - Build configuration +- `playwright.config.ts` - E2E test configuration + +## Testing Patterns + +### Test Fixture Patterns + +1. **examples/basic** - Comprehensive test suite + - Add test cases to `src/routes/` + - Update routing in `src/routes/root.tsx` + - Add tests to `e2e/basic.test.ts` + +2. **setupInlineFixture** - Isolated edge case testing + - Best for specific scenarios + - See `e2e/ssr-thenable.test.ts` for pattern + - Dependencies managed in `examples/e2e/package.json` + +### Adding Tests + +```bash +# Create new test project (automatically runnable) +pnpm -C packages/plugin-rsc/examples/e2e/temp/my-test dev +``` + +## Common Development Tasks + +### Adding New RSC Features + +1. Understand the React Server Components specification +2. Check existing implementation in `src/environment/` +3. Add runtime support in appropriate environment +4. Update type definitions +5. Add comprehensive tests +6. Update documentation + +### Debugging Issues + +1. Use `examples/starter` for basic reproduction +2. Check environment-specific builds in `.vite/` +3. Examine RSC streams and manifests +4. Test across all three environments +5. Verify HMR behavior + +### Performance Optimization + +1. Analyze bundle outputs with metadata plugins +2. Check CSS code-splitting effectiveness +3. Monitor RSC payload sizes +4. Test streaming performance + +## Key Plugin APIs + +### Virtual Modules + +- `virtual:vite-rsc/assets-manifest` +- `virtual:vite-rsc/client-references` +- `virtual:vite-rsc/server-references` +- `virtual:vite-rsc/encryption-key` + +### Environment Helper API + +- `import.meta.viteRsc.loadCss()` - CSS loading +- `?vite-rsc-css-export=` - CSS exports + +### Runtime Modules + +- `@vitejs/plugin-rsc/rsc` - Server component rendering +- `@vitejs/plugin-rsc/ssr` - SSR utilities +- `@vitejs/plugin-rsc/browser` - Client-side RSC + +## Best Practices + +1. **Use setupInlineFixture for new tests** - More maintainable and faster +2. **Follow existing patterns** - Check `examples/basic` for comprehensive examples +3. **Test across environments** - Ensure functionality works in rsc, ssr, and client +4. **Maintain backward compatibility** - RSC ecosystem is evolving rapidly +5. **Document breaking changes** - Update CHANGELOG.md appropriately + +## Troubleshooting + +### Common Issues + +1. **Module resolution errors** - Check `optimizeDeps.include` configuration +2. **CSS not loading** - Verify `loadCss()` usage and environment setup +3. **HMR not working** - Check component boundaries and environment isolation +4. **Build failures** - Verify environment-specific configurations + +### Debugging Tools + +- Vite's built-in inspect plugin +- Browser DevTools for client environment +- Server logs for rsc/ssr environments +- Playwright test inspector for e2e tests + +For more detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). From 1098fcb56e81d39ee278f04ad664eb46ad190e92 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 7 Sep 2025 07:46:00 +0000 Subject: [PATCH 3/4] Refactor AGENTS.md files to reference existing documentation Co-authored-by: hi-ogawa <4232207+hi-ogawa@users.noreply.github.com> --- AGENTS.md | 145 +++++++------------------- packages/plugin-rsc/AGENTS.md | 186 ++++++---------------------------- 2 files changed, 65 insertions(+), 266 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f81080d5..59c2e181 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,131 +1,56 @@ # AI Agent Development Guide -This document provides guidance for AI agents working with the vite-plugin-react monorepo. +This document provides AI-agent-specific guidance for working with the vite-plugin-react monorepo. For comprehensive documentation, see: -## Repository Structure +- **[README.md](README.md)** - Repository overview and package links +- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Setup, testing, debugging, and contribution guidelines -This is a monorepo containing multiple Vite React plugins: +## Quick Reference for AI Agents -``` -packages/ -├── plugin-react/ # Main React plugin with Babel transformation -├── plugin-react-swc/ # React plugin with SWC transformation -├── plugin-react-oxc/ # Deprecated React plugin (merged with plugin-react) -├── plugin-rsc/ # React Server Components plugin -└── common/ # Shared utilities -``` +### Repository Navigation -## Development Workflow +This monorepo contains multiple packages (see [README.md](README.md#packages) for details): -### Prerequisites +- `packages/plugin-react/` - Main React plugin with Babel +- `packages/plugin-react-swc/` - SWC-based React plugin +- `packages/plugin-rsc/` - React Server Components ([AI guidance](packages/plugin-rsc/AGENTS.md)) +- `packages/plugin-react-oxc/` - Deprecated (merged with plugin-react) -- Node.js ^20.19.0 || >=22.12.0 -- pnpm (package manager) - version 10.15.0 - -### Setup +### Essential Setup Commands ```bash -# Install dependencies -pnpm install - -# Build all packages -pnpm build - -# Start development mode (watch builds) -pnpm dev +pnpm install && pnpm build # Initial setup (see CONTRIBUTING.md for details) +pnpm dev # Watch mode development +pnpm test # Run all tests ``` -### Key Commands - -```bash -# Linting -pnpm lint # ESLint across all packages -pnpm format # Prettier formatting - -# Type checking -pnpm typecheck # TypeScript checking - -# Testing -pnpm test # Run all tests -pnpm test-unit # Unit tests only -pnpm test-serve # Development server tests -pnpm test-build # Build tests -``` - -## Important Files - -- `package.json` - Monorepo configuration and scripts -- `pnpm-workspace.yaml` - Workspace configuration -- `eslint.config.js` - ESLint configuration -- `playground/` - Test applications for each plugin - -## Plugin-Specific Notes - -### @vitejs/plugin-react - -- Located in `packages/plugin-react/` -- Uses Babel for transformation -- Primary React plugin for Vite - -### @vitejs/plugin-react-swc - -- Located in `packages/plugin-react-swc/` -- Uses SWC for faster transformation -- Alternative to Babel-based plugin - -### @vitejs/plugin-rsc - -- Located in `packages/plugin-rsc/` -- Experimental React Server Components support -- See [packages/plugin-rsc/AGENTS.md](packages/plugin-rsc/AGENTS.md) for detailed guidance - -## Testing Guidelines - -Each package has its own test suite. The playground directory contains integration tests that verify plugin functionality in realistic scenarios. - -### Running Package-Specific Tests - -```bash -# Test specific package -pnpm --filter ./packages/plugin-react test -pnpm --filter ./packages/plugin-rsc test-e2e -``` - -## Code Quality - -- Code is automatically formatted with Prettier on commit -- ESLint enforces code quality and consistency -- TypeScript provides type safety -- All packages require tests for new features +### AI-Specific Workflow Tips -## Contributing +1. **Start with existing documentation** - Always read package-specific READMEs before making changes +2. **Use playground tests** - Each package has `playground/` examples for testing changes +3. **Focus on minimal changes** - Prefer surgical edits over large refactors +4. **Test early and often** - Run `pnpm test` after each logical change +5. **Follow existing patterns** - Study similar implementations in the codebase first -1. Follow the existing code style and patterns -2. Add tests for new functionality -3. Update documentation as needed -4. Ensure all linting and tests pass -5. Keep changes focused and atomic +### Common Development Tasks -## Common Tasks for AI Agents +#### Making Changes to Plugin Logic -### Adding a New Feature +1. Read the package README and existing code patterns +2. Use `pnpm dev` for watch mode during development +3. Test changes with relevant playground examples +4. Run tests: `pnpm test-serve` and `pnpm test-build` -1. Identify the appropriate package -2. Read existing code patterns -3. Add implementation with proper TypeScript types -4. Add comprehensive tests -5. Update relevant documentation +#### Debugging Build Issues -### Debugging Issues +1. Check individual package builds with `pnpm --filter ./packages/ build` +2. Use playground tests to isolate problems +3. See [CONTRIBUTING.md debugging section](CONTRIBUTING.md#debugging) for detailed guidance -1. Check playground tests for reproduction cases -2. Use `pnpm dev` for live development -3. Run specific test suites to isolate problems -4. Review build outputs and error messages +#### Adding Tests -### Performance Optimization +1. Follow patterns in existing `__tests__` directories +2. Use playground integration tests for feature verification +3. See [CONTRIBUTING.md testing section](CONTRIBUTING.md#running-tests) for comprehensive testing guide -1. Profile with `vite-plugin-inspect` -2. Analyze bundle sizes in playground builds -3. Test with various React application patterns -4. Ensure backward compatibility +For detailed development setup, testing procedures, and contribution guidelines, refer to [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/packages/plugin-rsc/AGENTS.md b/packages/plugin-rsc/AGENTS.md index f65c19cd..e495e999 100644 --- a/packages/plugin-rsc/AGENTS.md +++ b/packages/plugin-rsc/AGENTS.md @@ -1,180 +1,54 @@ # AI Agent Guide for @vitejs/plugin-rsc -This document provides specific guidance for AI agents working with the React Server Components (RSC) plugin. +This document provides AI-agent-specific guidance for the React Server Components (RSC) plugin. For comprehensive documentation, see: -## Overview +- **[README.md](README.md)** - Plugin overview, concepts, and examples +- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development setup and testing guidelines -The `@vitejs/plugin-rsc` provides React Server Components support for Vite. It's built on the Vite environment API and enables: +## Quick Reference for AI Agents -- Framework-agnostic RSC bundler features -- HMR support for both client and server components -- CSS code-splitting and injection -- Runtime-agnostic builds (works with various deployment targets) +### Key Plugin Concepts -## Key Concepts +The RSC plugin creates three environments (see [README.md Basic Concepts](README.md#basic-concepts) for diagrams): -### Environments +- **rsc** - Server component rendering +- **ssr** - Server-side rendering +- **client** - Browser hydration -The plugin creates three distinct environments: - -1. **rsc** - React server components rendering -2. **ssr** - Server-side rendering environment -3. **client** - Browser environment for hydration - -### Architecture - -``` -RSC Component → RSC Stream → SSR/Client Consumption → DOM/HTML -``` - -See [Basic Concepts](README.md#basic-concepts) in the README for detailed flow diagrams. - -## Development Workflow - -### Setup +### Essential Commands ```bash -# Build the plugin -pnpm -C packages/plugin-rsc dev - -# Type checking -pnpm -C packages/plugin-rsc tsc-dev +pnpm -C packages/plugin-rsc dev # Watch mode development +pnpm -C packages/plugin-rsc test-e2e # Run e2e tests +pnpm -C packages/plugin-rsc test-e2e basic # Test specific example ``` -### Testing +### AI-Specific Development Tips -```bash -# Run all e2e tests -pnpm -C packages/plugin-rsc test-e2e - -# Run with UI (interactive filtering) -pnpm -C packages/plugin-rsc test-e2e --ui +#### Making RSC Changes -# Run specific test file -pnpm -C packages/plugin-rsc test-e2e basic +1. **Start with `examples/starter/`** - Best learning resource for understanding RSC flows +2. **Use `examples/basic/` for testing** - Comprehensive test suite with routing +3. **Test across all environments** - Verify rsc, ssr, and client functionality +4. **Check virtual modules** - Important for RSC manifest and reference handling -# Run with grep filter -pnpm -C packages/plugin-rsc test-e2e -g "hmr" -``` +#### Testing Patterns -### Examples +- **examples/basic** - Add test cases to `src/routes/`, update routing, add tests to `e2e/basic.test.ts` +- **setupInlineFixture** - For isolated edge cases (see `e2e/ssr-thenable.test.ts` pattern) -- `examples/starter/` - **Start here** - Comprehensive learning resource -- `examples/basic/` - Advanced features and main e2e test suite -- `examples/ssg/` - Static site generation example -- `examples/react-router/` - React Router integration - -## Important Files - -### Core Plugin Files +#### Important File Locations - `src/plugin.ts` - Main plugin implementation - `src/environment/` - Environment-specific logic -- `src/types/` - TypeScript definitions -- `types/` - External type definitions - -### Runtime APIs - -- `rsc/` - Server component runtime -- `ssr/` - SSR runtime -- `browser/` - Client runtime -- `vendor/` - Vendored react-server-dom - -### Configuration - -- `vite.config.ts` - Development configuration -- `tsdown.config.ts` - Build configuration -- `playwright.config.ts` - E2E test configuration +- `rsc/`, `ssr/`, `browser/` - Runtime APIs +- `examples/` - Test applications and learning resources -## Testing Patterns - -### Test Fixture Patterns - -1. **examples/basic** - Comprehensive test suite - - Add test cases to `src/routes/` - - Update routing in `src/routes/root.tsx` - - Add tests to `e2e/basic.test.ts` - -2. **setupInlineFixture** - Isolated edge case testing - - Best for specific scenarios - - See `e2e/ssr-thenable.test.ts` for pattern - - Dependencies managed in `examples/e2e/package.json` - -### Adding Tests - -```bash -# Create new test project (automatically runnable) -pnpm -C packages/plugin-rsc/examples/e2e/temp/my-test dev -``` - -## Common Development Tasks - -### Adding New RSC Features - -1. Understand the React Server Components specification -2. Check existing implementation in `src/environment/` -3. Add runtime support in appropriate environment -4. Update type definitions -5. Add comprehensive tests -6. Update documentation - -### Debugging Issues +### Debugging RSC Issues 1. Use `examples/starter` for basic reproduction -2. Check environment-specific builds in `.vite/` -3. Examine RSC streams and manifests -4. Test across all three environments -5. Verify HMR behavior - -### Performance Optimization - -1. Analyze bundle outputs with metadata plugins -2. Check CSS code-splitting effectiveness -3. Monitor RSC payload sizes -4. Test streaming performance - -## Key Plugin APIs - -### Virtual Modules - -- `virtual:vite-rsc/assets-manifest` -- `virtual:vite-rsc/client-references` -- `virtual:vite-rsc/server-references` -- `virtual:vite-rsc/encryption-key` - -### Environment Helper API - -- `import.meta.viteRsc.loadCss()` - CSS loading -- `?vite-rsc-css-export=` - CSS exports - -### Runtime Modules - -- `@vitejs/plugin-rsc/rsc` - Server component rendering -- `@vitejs/plugin-rsc/ssr` - SSR utilities -- `@vitejs/plugin-rsc/browser` - Client-side RSC - -## Best Practices - -1. **Use setupInlineFixture for new tests** - More maintainable and faster -2. **Follow existing patterns** - Check `examples/basic` for comprehensive examples -3. **Test across environments** - Ensure functionality works in rsc, ssr, and client -4. **Maintain backward compatibility** - RSC ecosystem is evolving rapidly -5. **Document breaking changes** - Update CHANGELOG.md appropriately - -## Troubleshooting - -### Common Issues - -1. **Module resolution errors** - Check `optimizeDeps.include` configuration -2. **CSS not loading** - Verify `loadCss()` usage and environment setup -3. **HMR not working** - Check component boundaries and environment isolation -4. **Build failures** - Verify environment-specific configurations - -### Debugging Tools - -- Vite's built-in inspect plugin -- Browser DevTools for client environment -- Server logs for rsc/ssr environments -- Playwright test inspector for e2e tests +2. Check environment builds in `.vite/` directory +3. Examine RSC streams and client/server manifests +4. Verify HMR behavior across environments -For more detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). +For detailed setup, testing procedures, and architectural deep-dives, refer to the comprehensive documentation in [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md). From d98667339840778b2d8294d84f17ee63498496c2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 7 Sep 2025 07:59:29 +0000 Subject: [PATCH 4/4] Address feedback: simplify AGENTS.md files and add non-watch mode commands Co-authored-by: hi-ogawa <4232207+hi-ogawa@users.noreply.github.com> --- AGENTS.md | 31 ----------------------- packages/plugin-rsc/AGENTS.md | 47 +++++------------------------------ 2 files changed, 6 insertions(+), 72 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 59c2e181..955ffb01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,34 +23,3 @@ pnpm install && pnpm build # Initial setup (see CONTRIBUTING.md for details) pnpm dev # Watch mode development pnpm test # Run all tests ``` - -### AI-Specific Workflow Tips - -1. **Start with existing documentation** - Always read package-specific READMEs before making changes -2. **Use playground tests** - Each package has `playground/` examples for testing changes -3. **Focus on minimal changes** - Prefer surgical edits over large refactors -4. **Test early and often** - Run `pnpm test` after each logical change -5. **Follow existing patterns** - Study similar implementations in the codebase first - -### Common Development Tasks - -#### Making Changes to Plugin Logic - -1. Read the package README and existing code patterns -2. Use `pnpm dev` for watch mode during development -3. Test changes with relevant playground examples -4. Run tests: `pnpm test-serve` and `pnpm test-build` - -#### Debugging Build Issues - -1. Check individual package builds with `pnpm --filter ./packages/ build` -2. Use playground tests to isolate problems -3. See [CONTRIBUTING.md debugging section](CONTRIBUTING.md#debugging) for detailed guidance - -#### Adding Tests - -1. Follow patterns in existing `__tests__` directories -2. Use playground integration tests for feature verification -3. See [CONTRIBUTING.md testing section](CONTRIBUTING.md#running-tests) for comprehensive testing guide - -For detailed development setup, testing procedures, and contribution guidelines, refer to [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/packages/plugin-rsc/AGENTS.md b/packages/plugin-rsc/AGENTS.md index e495e999..1b75ef7b 100644 --- a/packages/plugin-rsc/AGENTS.md +++ b/packages/plugin-rsc/AGENTS.md @@ -7,48 +7,13 @@ This document provides AI-agent-specific guidance for the React Server Component ## Quick Reference for AI Agents -### Key Plugin Concepts - -The RSC plugin creates three environments (see [README.md Basic Concepts](README.md#basic-concepts) for diagrams): - -- **rsc** - Server component rendering -- **ssr** - Server-side rendering -- **client** - Browser hydration - ### Essential Commands ```bash -pnpm -C packages/plugin-rsc dev # Watch mode development -pnpm -C packages/plugin-rsc test-e2e # Run e2e tests -pnpm -C packages/plugin-rsc test-e2e basic # Test specific example +# inside packages/plugin-rsc directory +pnpm build # build package +pnpm tsc # typecheck +pnpm dev # Watch mode development +pnpm test-e2e # Run e2e tests +pnpm test-e2e basic # Test specific example ``` - -### AI-Specific Development Tips - -#### Making RSC Changes - -1. **Start with `examples/starter/`** - Best learning resource for understanding RSC flows -2. **Use `examples/basic/` for testing** - Comprehensive test suite with routing -3. **Test across all environments** - Verify rsc, ssr, and client functionality -4. **Check virtual modules** - Important for RSC manifest and reference handling - -#### Testing Patterns - -- **examples/basic** - Add test cases to `src/routes/`, update routing, add tests to `e2e/basic.test.ts` -- **setupInlineFixture** - For isolated edge cases (see `e2e/ssr-thenable.test.ts` pattern) - -#### Important File Locations - -- `src/plugin.ts` - Main plugin implementation -- `src/environment/` - Environment-specific logic -- `rsc/`, `ssr/`, `browser/` - Runtime APIs -- `examples/` - Test applications and learning resources - -### Debugging RSC Issues - -1. Use `examples/starter` for basic reproduction -2. Check environment builds in `.vite/` directory -3. Examine RSC streams and client/server manifests -4. Verify HMR behavior across environments - -For detailed setup, testing procedures, and architectural deep-dives, refer to the comprehensive documentation in [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).