Add streaming support for Next.js App Router

[omidkazemi1]

This PR adds a new stream_nextjs_page function that enables streaming responses directly from Next.js to the client. This feature is particularly valuable for projects using Next.js 13+ with the App Router, supporting key Next.js features like instant loading states and streaming server components. Before this PR, the package couldn't properly support Next.js App Router's streaming capabilities, which are becoming increasingly important with Next.js 13+ and particularly Next.js 15. Features like loading UI, streaming, and suspense boundaries in Next.js require the ability to stream HTML rather than waiting for the full response.

Note: When using stream_nextjs_page, you cannot use a custom HTML template in Django, as the HTML is streamed directly from the Next.js server.

[mjnaderi]

Thanks for this valuable contribution! Streaming support is definitely crucial for modern Next.js applications, especially with the App Router becoming the standard.

Regarding the implementation, I have a few suggestions to streamline the API and documentation:

• Prioritize Streaming in Docs: I think it would be best to present the new streaming approach as the primary method in the documentation. We can then introduce the older method afterward, clearly stating its limitations (no App Router or streaming support) but highlighting its advantage of allowing Django template customization. It might also be worth mentioning the possibility of future deprecation for the older method, or even formally deprecating it now to encourage adoption of the new approach.

• Internal stream_nextjs_page (and the rationale behind it): Let's aim to keep the public API focused on nextjs_page and do not have stream_nextjs_page in the public API. The goal here isn't solely about having a cleaner API. By making the streaming functionality an internal part of nextjs_page, we actively encourage users to adopt the nextjs_page pattern for rendering Next.js pages. The key advantage of nextjs_page is that it avoids the need for users to write explicit Django views for their Next.js pages. If users write their own Django views and directly use a function like stream_nextjs_page within them, they might be tempted to include business logic (like database interactions or analytics tracking) directly in these views. This logic would then only execute when the page is initially loaded directly, but not during client-side navigation within the Next.js application. To ensure consistent behavior and leverage Next.js's client-side rendering capabilities effectively, we strongly recommend using nextjs_page as the way to serve Next.js content.

• stream Parameter in nextjs_page: We could add a boolean stream parameter to the nextjs_page function, defaulting to False. If set to True, the view would be handled using the underlying streaming logic (currently in stream_nextjs_page).

• Parameter Validation with Streaming: To avoid confusion and potential errors, if stream=True is passed to nextjs_page, we should raise an exception if any of template_name, context, or using are also provided. This clearly communicates that these parameters are incompatible with streaming.

By consolidating the functionality within nextjs_page and clearly documenting the new streaming capabilities as the recommended approach, we can provide a more intuitive and future-proof integration for django-nextjs users.

It's worth noting that this PR closes #22.

[mjnaderi]

@danialkeimasi I'd also be really interested to hear your thoughts on this PR and these suggestions.

[danialkeimasi]

I believe the default value of the stream argument in nextjs_page should be set to True. Our API should be designed with newer versions in mind, and most Next.js users now prefer streaming by default. I suggest we first make a backward-compatible release with stream=False, followed by a major release where stream=True becomes the default.