Skip to content

Commit 7e4f858

Browse files
CopilotRich-Harris
Copilot
and
Rich-Harris
authored
Add comprehensive GitHub Copilot instructions for SvelteKit development (#14186)
* Initial plan * Add comprehensive GitHub Copilot instructions for SvelteKit development Co-authored-by: Rich-Harris <[email protected]> --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Rich-Harris <[email protected]>
1 parent 2326d96 commit 7e4f858

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# SvelteKit Development Instructions
2+
3+
SvelteKit is a web application framework for building modern web applications with Svelte. This is a monorepo containing @sveltejs/kit, adapters, and related packages.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Prerequisites and Setup
10+
- Install Node.js 18+ (current tested versions: 18, 20, 22, 24)
11+
- Install pnpm globally: `npm install -g pnpm` (takes ~2 seconds)
12+
- Clone the repository: `git clone [email protected]:sveltejs/kit.git`
13+
- Navigate to the repository: `cd kit`
14+
15+
### Bootstrap and Build Commands
16+
- **CRITICAL**: Install dependencies: `pnpm install --frozen-lockfile`
17+
- **NEVER CANCEL**: Takes 3-4 minutes. Set timeout to 10+ minutes.
18+
- Sync generated files: `pnpm run sync-all` (takes <1 second)
19+
- Build all packages: `pnpm build` (takes ~1-2 seconds)
20+
21+
### Development Commands
22+
- **Format code**: `pnpm run format` (takes ~15 seconds)
23+
- **Lint code**: `pnpm run lint`
24+
- **NEVER CANCEL**: Takes 2-3 minutes. Set timeout to 5+ minutes.
25+
- **Type checking**: `pnpm run check`
26+
- **NEVER CANCEL**: Takes 3-4 minutes. Set timeout to 8+ minutes.
27+
- **Run unit tests**: `cd packages/kit && pnpm test:unit` (takes ~6 seconds)
28+
29+
### Testing Commands
30+
- **Unit tests only**: `cd packages/kit && pnpm test:unit` (takes ~6 seconds)
31+
- **Integration tests**: `pnpm test:kit`
32+
- **NEVER CANCEL**: Takes 10-30 minutes. Set timeout to 60+ minutes.
33+
- **Requires browser setup**: `pnpm playwright install chromium` first
34+
- **Other package tests**: `pnpm test:others`
35+
- **NEVER CANCEL**: Takes 5-15 minutes. Set timeout to 30+ minutes.
36+
- **Requires browser setup**: `pnpm playwright install chromium` first
37+
38+
### Development Server (Playground)
39+
- Navigate to playground: `cd playgrounds/basic`
40+
- Start dev server: `pnpm run dev`
41+
- Server starts at: `http://localhost:5173/`
42+
- Dev server starts in ~1-2 seconds
43+
44+
## Validation Requirements
45+
46+
### ALWAYS run these before submitting changes:
47+
1. `pnpm run format` - Auto-format all code
48+
2. `pnpm run lint` - Check code style (NEVER CANCEL - takes 2-3 minutes)
49+
3. `pnpm run check` - Type checking (NEVER CANCEL - takes 3-4 minutes)
50+
4. `cd packages/kit && pnpm test:unit` - Run unit tests
51+
5. **For changes to @sveltejs/kit**: `cd packages/kit && pnpm prepublishOnly` - Generate types
52+
53+
### Manual Testing Scenarios
54+
**ALWAYS test these scenarios after making changes:**
55+
56+
1. **Create a new SvelteKit app**:
57+
```bash
58+
cd /tmp
59+
npx sv create test-app --template minimal --no-install --no-types
60+
# Press Enter to skip additional packages
61+
cd test-app
62+
npm install
63+
npm run dev
64+
```
65+
- Verify the app starts and loads at http://localhost:5173/
66+
67+
2. **Test the CLI**:
68+
```bash
69+
cd packages/kit
70+
node svelte-kit.js --help
71+
node svelte-kit.js sync --help
72+
```
73+
74+
3. **Test playground functionality**:
75+
```bash
76+
cd playgrounds/basic
77+
pnpm run dev
78+
```
79+
- Navigate to http://localhost:5173/
80+
- Test basic navigation and functionality
81+
82+
## Repository Structure
83+
84+
### Key Packages (`packages/` directory):
85+
- **@sveltejs/kit** - Main SvelteKit package (`packages/kit/`)
86+
- **Adapters**: adapter-auto, adapter-cloudflare, adapter-netlify, adapter-node, adapter-static, adapter-vercel
87+
- **@sveltejs/enhanced-img** - Enhanced image component
88+
- **@sveltejs/package** - Package building utilities
89+
- **@sveltejs/amp** - AMP support
90+
91+
### Key Directories:
92+
- `packages/kit/src/core/` - Build-time code
93+
- `packages/kit/src/runtime/` - Runtime code
94+
- `packages/kit/src/exports/vite/` - Vite plugin
95+
- `packages/kit/test/` - Integration tests
96+
- `playgrounds/basic/` - Development playground
97+
- `.github/workflows/` - CI/CD configuration
98+
99+
### Important Files:
100+
- `pnpm-workspace.yaml` - Workspace configuration
101+
- `package.json` - Root package with scripts
102+
- `packages/kit/svelte-kit.js` - CLI entry point
103+
- `packages/kit/package.json` - Main package configuration
104+
105+
## Common Tasks
106+
107+
### Working with Types
108+
- Generate types: `cd packages/kit && pnpm generate:types`
109+
- Check types: `cd packages/kit && pnpm prepublishOnly`
110+
- **CRITICAL**: Always commit generated type changes
111+
112+
### Testing Specific Changes
113+
- Link local changes to external project using `pnpm.overrides` in external project's package.json:
114+
```json
115+
{
116+
"pnpm": {
117+
"overrides": {
118+
"@sveltejs/kit": "link:../path/to/kit/packages/kit"
119+
}
120+
}
121+
}
122+
```
123+
124+
### Working with Adapters
125+
- Each adapter has its own test suite
126+
- Build adapter: `cd packages/adapter-[name] && pnpm build`
127+
- Test adapter: `cd packages/adapter-[name] && pnpm test`
128+
129+
## Timing Expectations
130+
131+
**Set these timeout values for long-running commands:**
132+
133+
| Command | Expected Time | Recommended Timeout |
134+
|---------|---------------|-------------------|
135+
| `pnpm install --frozen-lockfile` | 3-4 minutes | 10+ minutes |
136+
| `pnpm run lint` | 2-3 minutes | 5+ minutes |
137+
| `pnpm run check` | 3-4 minutes | 8+ minutes |
138+
| `pnpm test:kit` | 10-30 minutes | 60+ minutes |
139+
| `pnpm test:others` | 5-15 minutes | 30+ minutes |
140+
| `pnpm run format` | ~15 seconds | 2+ minutes |
141+
| `pnpm build` | 1-2 seconds | 2+ minutes |
142+
| Dev server startup | 1-2 seconds | 1+ minute |
143+
| Unit tests | ~6 seconds | 2+ minutes |
144+
145+
## Troubleshooting
146+
147+
### Browser Tests Fail
148+
- Install Playwright browsers: `pnpm playwright install chromium`
149+
- For full browser support: `pnpm playwright install`
150+
151+
### Build Failures
152+
- Ensure all dependencies installed: `pnpm install --frozen-lockfile`
153+
- Regenerate types: `cd packages/kit && pnpm prepublishOnly`
154+
- Check for TypeScript errors: `pnpm run check`
155+
156+
### Lint/Format Issues
157+
- Auto-fix formatting: `pnpm run format`
158+
- Check specific package: `cd packages/[name] && pnpm lint`
159+
160+
### Development Server Issues
161+
- Ensure sync is complete: `pnpm run sync-all`
162+
- Check for port conflicts (default: 5173)
163+
- Restart with clean cache: Clear node_modules and reinstall
164+
165+
## Git Hooks
166+
Configure git hooks for automatic validation:
167+
```bash
168+
git config core.hookspath .githooks
169+
```
170+
171+
## Output Examples
172+
173+
### Successful pnpm install completion:
174+
```
175+
Done in 2m 48.5s using pnpm v10.14.0
176+
```
177+
178+
### Successful dev server startup:
179+
```
180+
VITE v6.3.5 ready in 1145 ms
181+
➜ Local: http://localhost:5173/
182+
```
183+
184+
### CLI help output:
185+
```
186+
Usage
187+
$ svelte-kit <command> [options]
188+
189+
Available Commands
190+
sync Synchronise generated type definitions
191+
```

0 commit comments

Comments
 (0)