Skip to content

Commit 6f5974e

Browse files
CopilotNonSwag
Copilot
and
NonSwag
committed
Create comprehensive copilot-instructions.md with validated commands
Co-authored-by: NonSwag <[email protected]>
1 parent 008a96c commit 6f5974e

File tree

2 files changed

+10259
-0
lines changed

2 files changed

+10259
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# TheNextLvl Documentation Website
2+
3+
TheNextLvl documentation is a Next.js 15 application built with Fumadocs, TypeScript, and Tailwind CSS. It serves as the documentation site for TheNextLvl Minecraft server community plugins and services, accessible at https://thenextlvl.net.
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+
### Bootstrap, Build, and Development
10+
11+
- **CRITICAL**: Some commands have network dependencies that may fail in restricted environments
12+
- Install dependencies:
13+
- Preferred: `bun install` -- takes ~1-24 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
14+
- Fallback: `npm install` -- takes ~71 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
15+
- Development server:
16+
- `bun run dev` or `npm run dev` -- starts in ~1 second, runs on http://localhost:3000
17+
- NEVER CANCEL: Development server runs indefinitely until stopped
18+
- Production build:
19+
- `bun run build` or `npm run build`
20+
- **WARNING**: Build fails in restricted network environments due to:
21+
1. Google Fonts (fonts.gstatic.com) access required for Inter font
22+
2. API calls to repo.thenextlvl.net for version information
23+
- Build takes ~20-30 seconds when network is available
24+
- If build fails with network errors, this is expected in sandboxed environments
25+
26+
### Package Manager Setup
27+
28+
- **Install Bun** (if not available):
29+
```bash
30+
curl -fsSL https://bun.sh/install | bash
31+
source ~/.bashrc
32+
bun --version
33+
```
34+
- The project specifies `[email protected]` as the package manager in package.json
35+
- Node.js fallback is supported for all commands
36+
37+
### Linting and Formatting
38+
39+
- **Format code**: `bun run format` or `npm run format` -- takes ~1 second. Uses Prettier.
40+
- **Lint code**: `npx next lint` -- takes ~3 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
41+
- Note: Shows warnings about TypeScript version mismatch (expected)
42+
- May show img element and unused variable warnings (expected)
43+
- **CRITICAL**: Always run formatting and linting before pushing changes or CI will fail
44+
45+
## Validation Scenarios
46+
47+
### Manual Testing Requirements
48+
49+
After making changes, ALWAYS perform these validation steps:
50+
51+
1. **Start development server**:
52+
- Run `bun run dev` or `npm run dev`
53+
- Verify server starts on http://localhost:3000 in ~1 second
54+
- Test homepage loads: `curl -s http://localhost:3000 | head -10`
55+
- Verify you see HTML content starting with `<!DOCTYPE html>`
56+
57+
2. **Test documentation pages**:
58+
- Navigate to http://localhost:3000/docs
59+
- **Note**: Pages may show 500 errors in restricted networks due to API calls - this is expected
60+
- In normal environments, verify navigation and content display works
61+
62+
3. **Validate formatting and linting**:
63+
- Run `bun run format` or `npm run format` - should complete in ~1 second without errors
64+
- Run `npx next lint` - should complete in ~3 seconds with minimal warnings only
65+
- Expected warnings: img element usage, unused variables (these are normal)
66+
67+
## Key Architecture
68+
69+
### Directory Structure
70+
71+
```
72+
.
73+
├── README.md # Project overview and getting started
74+
├── package.json # Dependencies and scripts
75+
├── source.config.ts # Fumadocs MDX configuration
76+
├── next.config.mjs # Next.js configuration with redirects
77+
├── tsconfig.json # TypeScript configuration
78+
├── .eslintrc.json # ESLint configuration (legacy format)
79+
├── .prettierrc.json # Prettier configuration
80+
├── postcss.config.mjs # PostCSS with Tailwind
81+
├── content/ # Documentation content in MDX
82+
│ └── docs/ # Main docs content
83+
├── src/ # Application source code
84+
│ ├── app/ # Next.js App Router
85+
│ ├── lib/ # Utility libraries
86+
│ └── mdx-components.tsx # MDX component overrides
87+
├── public/ # Static assets
88+
└── .github/ # GitHub workflows and configuration
89+
└── workflows/build.yml # CI build workflow
90+
```
91+
92+
### Key Files to Know
93+
94+
- `src/lib/api.ts` - Contains API calls to repo.thenextlvl.net (causes network issues)
95+
- `src/app/layout.tsx` - Main app layout with Inter font from Google Fonts
96+
- `src/lib/source.ts` - Fumadocs content source configuration
97+
- `content/docs/` - All documentation content in MDX format
98+
- `.github/workflows/build.yml` - CI pipeline using Bun
99+
100+
### Content System
101+
102+
- Uses Fumadocs with MDX for documentation
103+
- Content lives in `content/docs/` directory
104+
- Each section has `meta.json` for navigation configuration
105+
- Some pages import `latestVersion` function from `src/lib/api.ts` for dynamic version display
106+
107+
## Common Tasks and Troubleshooting
108+
109+
### Network-Related Issues
110+
111+
- **Google Fonts errors**: Expected in restricted environments. Font loading fails but app still functions.
112+
- **repo.thenextlvl.net errors**: API calls for version information fail in restricted networks.
113+
- **Workaround**: For testing, temporarily comment out font imports and API calls if needed.
114+
115+
### Build Issues
116+
117+
- If build fails with "fetch failed" errors, this indicates network restrictions
118+
- Development mode (`bun run dev`) works even when build fails
119+
- Production build requires internet access for fonts and API calls
120+
121+
### Dependencies
122+
123+
- Always use `bun install` when possible (much faster than npm)
124+
- If Bun unavailable, `npm install` works as fallback
125+
- No test suite exists - validation is done through manual testing
126+
127+
### Making Content Changes
128+
129+
- Edit MDX files in `content/docs/` directory
130+
- Changes are hot-reloaded in development mode
131+
- Some content files use `await latestVersion()` calls that require network access
132+
- Always test documentation navigation after content changes
133+
134+
## CI/CD Integration
135+
136+
### GitHub Actions
137+
138+
- Workflow: `.github/workflows/build.yml`
139+
- Runs on: Ubuntu latest with Bun
140+
- Steps: checkout → setup bun → install dependencies → build
141+
- Environment variable: `NEXT_PUBLIC_BASE_URL: https://thenextlvl.net`
142+
- Build must pass for deployment
143+
144+
### Pre-commit Checklist
145+
146+
1. Run `bun run format` or `npm run format` - ensure all files formatted (~1 second)
147+
2. Run `npx next lint` - check for linting issues (~3 seconds, warnings OK)
148+
3. Test development server starts: `bun run dev` or `npm run dev` (~1 second)
149+
4. Verify content changes display correctly at http://localhost:3000
150+
5. Test homepage accessibility: `curl -s http://localhost:3000 | head -10`
151+
6. Check that new files follow existing patterns
152+
153+
## Network Dependencies Summary
154+
155+
- **Google Fonts**: Inter font family (fonts.gstatic.com)
156+
- **Version API**: repo.thenextlvl.net for plugin version info
157+
- **Expected failures**: Both may fail in sandboxed/restricted environments
158+
- **Impact**: Development server works, but production build may fail

0 commit comments

Comments
 (0)