middleware/proxy fixes for next.js 15/16

[leoortizz]

Description

This PR updates the Next.js framework adapter to seamlessly support middleware changes introduced in Next.js 16, specifically handling both the new proxy convention and the deprecated middleware convention.

• Next.js 16 Support: Implements support for reading middleware configuration from functions-config-manifest.json, ensuring compatibility with Next.js 16's Node.js runtime middleware (proxy.ts/js).
• Backward Compatibility: Adds a fallback mechanism to support the deprecated middleware.ts/js convention by reading from middleware-manifest.json.
• Dev Mode Detection: Updates isUsingMiddleware to automatically detect proxy.js and proxy.ts files in development mode, in addition to existing checks.
• Type Definitions: Adds comprehensive TypeScript interfaces for Next.js 16 manifests (FunctionsConfigManifest, MiddlewareManifestV3, etc.) with documentation linking to the source.
• Test Refactoring: Reorganizes middleware tests by version and environment for better clarity and maintainability, adding specific test cases for deprecated middleware scenarios and proxy detection.

Scenarios Tested

• Confirmed that middleware matchers are correctly extracted from functions-config-manifest.json when using the new proxy.ts convention.
• Confirmed that the adapter correctly falls back to middleware-manifest.json when using the deprecated middleware.ts convention.
• Verified detection of proxy.js/ts alongside middleware.js/ts in dev mode(emulator).
• Verified correct middleware detection and matcher extraction based on manifest presence when deployed.

Sample Commands

firebase deploy will now automatically handle Next.js 16 projects using either the new proxy or legacy middleware conventions without user intervention.

[gemini-code-assist]

Summary of Changes

Hello @leoortizz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Next.js framework adapter to ensure full compatibility with Next.js 16. It introduces support for the new proxy convention for middleware while meticulously preserving backward compatibility for projects still utilizing the deprecated middleware convention. The core purpose is to provide a seamless and robust deployment experience for Next.js applications on Firebase, adapting to the latest framework changes without requiring manual intervention from developers.

Highlights

• Next.js 16 Support: The adapter now supports reading middleware configuration from functions-config-manifest.json, ensuring compatibility with Next.js 16's Node.js runtime middleware (proxy.ts/js).
• Backward Compatibility: A fallback mechanism has been added to support the deprecated middleware.ts/js convention by reading from middleware-manifest.json.
• Dev Mode Detection: The isUsingMiddleware function has been updated to automatically detect proxy.js and proxy.ts files in development mode, in addition to existing checks for middleware.js/ts.
• Type Definitions: Comprehensive TypeScript interfaces for Next.js 16 manifests, including FunctionsConfigManifest and MiddlewareManifestV3, have been added with documentation linking to their source.
• Test Refactoring: Middleware tests have been reorganized by version and environment for improved clarity and maintainability, with new test cases specifically covering deprecated middleware scenarios and proxy detection.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request does an excellent job of updating the Next.js framework adapter to support middleware changes in Next.js 15 and 16, particularly the new proxy convention. The implementation correctly reads from functions-config-manifest.json while maintaining backward compatibility by falling back to middleware-manifest.json. The updates to development mode detection and the addition of comprehensive TypeScript definitions with source links are great for maintainability. The test suite has also been thoughtfully refactored to cover the new scenarios. My feedback is focused on minor improvements to the new TypeScript interfaces to enhance consistency and reusability.

[annajowang]

Are there reasonable more descriptive names that could be used instead of V1 or V3?

Are these all just different manifest types introduced at different nextjs versions?

For example could MiddlewareManifestNext16 or something work for MiddlewareManifestV3 ?

[annajowang]

ah nvm, these are literally the versions on the interface itself.

[annajowang]

Actually, would we some day remove support for very old nextjs versions? In which case would some of these manifest versions would no longer be needed? could those versions be in the docstrings for MiddlewareManifestv2 and v1 ?
I think the "Middleware manifest types for Next.js 16" you added for v3 is very helpful.

[leoortizz]

Actually, would we some day remove support for very old nextjs versions?

Deferring to @jamesdaniels, but I don't think we would remove support for old Next.js versions as they just work?

In which case would some of these manifest versions would no longer be needed?

The manifests won't be needed anymore as soon as we migrate to use the Adapters API. That's also why I chose to copy the V3 types instead of bumping the Next.js dependency, as it would require more changes that would not be necessary when we switch to the Adapters API.

could those versions be in the docstrings for MiddlewareManifestv2 and v1 ?
I think the "Middleware manifest types for Next.js 16" you added for v3 is very helpful.

The version of manifests does not match the Next.js version necessarily. I updated the comments to say in which versions they were used. I realized the manifest-middleware version 3 changed in Next.js 14.2.0, so I updated the comment. It's just that in Next.js 16 the proxy route matchers are in functions-config-manifest instead.

[annajowang]

More questions than feedback. As we're still ramping up I'll defer to james for final merge approval

[annajowang]

ah nvm, these are literally the versions on the interface itself.

[annajowang]

Actually, would we some day remove support for very old nextjs versions? In which case would some of these manifest versions would no longer be needed? could those versions be in the docstrings for MiddlewareManifestv2 and v1 ?
I think the "Middleware manifest types for Next.js 16" you added for v3 is very helpful.

[annajowang]

Was there a specific reason we decided not to copy v2 over like the others?

are we pinning to a specific version of the plugin somewhere? if that version gets wouldn't this break?

[leoortizz]

We're not copying it intentionally here to have less code, and to make sure we're matching the Next.js interfaces. It's coming directly from the Next.js source code as it's a dev dependency. It's currently ^14.1.0. If the dependency version changes this will indeed break, requiring manual changes. That's how we're making sure it's adhering to the types we want.

One alternative I tried in the past was to have multiple Next.js versions as dependencies(with aliases), enabling us to just import the types rather than rewriting them. However, that caused type errors, breaking the firebase-tools build.