What?

This PR adds validation to throw an error when root-level files (middleware and instrumentation) are found outside the src/ directory when a src/ directory structure is being used.

Why?

Currently, Next.js allows middleware and instrumentation files to exist at the project root even when using a src/ directory structure. This can lead to confusion and inconsistent file organization. The Next.js documentation states that when using the src directory, middleware should be placed inside the src folder, but this wasn't enforced.

How?

1. Added new error class: SrcDirectoryError in packages/next/src/build/utils.ts that provides clear error messaging and documentation links

2. Added validation functions:

   • validateMiddlewareInSrcDir(fileName: string, isSrcDir: boolean)
   • validateInstrumentationInSrcDir(fileName: string, isSrcDir: boolean)

3. Integrated validation in two key locations:

   • Development: packages/next/src/server/lib/router-utils/setup-dev-bundler.ts - validates during dev server startup
   • Build time: packages/next/src/build/index.ts - validates during production build

4. Added test cases: Created test/integration/src-dir-validation/ to verify the validation behavior

The validation logic checks:

• If src/ directory structure is being used (isSrcDir)
• If the file is a middleware or instrumentation file
• If the file is located outside the src/ directory
• If all conditions are true, throws SrcDirectoryError with helpful guidance

⚠️ Human Review Checklist

Critical items to verify:

1. File path logic: Verify that fileName.startsWith('/src/') correctly identifies files inside src directory for Next.js internal file paths
2. Test execution: Run the new tests in test/integration/src-dir-validation/ to ensure they work correctly
3. Existing tests: Confirm existing middleware-related tests still pass (especially test/integration/middleware-src)
4. Dev vs Build consistency: Test that validation works identically in both next dev and next build scenarios
5. Error message accuracy: Verify the documentation link in the error message is correct and helpful
6. Edge cases: Test scenarios like:
   • Projects without src directory (should not validate)
   • Projects with src directory but no middleware/instrumentation (should not error)
   • Mixed scenarios with some files in src and some outside

⚠️ Testing Gap: This implementation could not be tested locally due to missing pnpm dependency. The validation logic and integration points need thorough testing to ensure correctness.

Breaking Change Consideration: This introduces new fatal errors for previously "working" (but incorrectly organized) projects. Consider if this should be a warning first before becoming an error in a future version.

Link to Devin run: https://app.devin.ai/sessions/94e9f081963a4ec3bc8bc9c8c1ca8975
Requested by: @devjiwonchoi

🔄 This is a mirror of upstream PR #82514