feat: update documentation for version 2.5.0 of the Next.js SDK #305
Conversation
The upcoming 2.5.0 release of the Next.js SDK makes middleware significantly more important - it's now essential for efficient token refreshes. To signify this, the Middleware section has been moved up from the bottom of the page towards the getting started/configuration section and wording has been change to denote that it's now a requirement, not optional. The middleware matchers have been updated to the new 2.5.0 format as well.
WalkthroughThe pull request introduces enhancements to the documentation for the Kinde Auth SDK for Next.js. It adds a new section on customizing API paths, detailing how to set environment variables for various authentication routes. The middleware setup section has been expanded to include instructions for creating a Changes
Possibly related PRs
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (2)
81-87: Improve clarity and grammar in the middleware introduction.The introduction could be clearer with some minor adjustments:
Apply these changes to improve readability:
-Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience. +Middleware is used to protect routes in your Next.js app and is a requirement for a seamless authentication experience. -We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. +We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated, they are redirected to log in, and once they have logged in, they will be redirected back to the protected page they should now have access to.🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...(NOUN_VERB_CONFUSION)
87-87: Fix verb usage in the public routes section.The hyphenated form "opt-out" is being used as a verb.
Apply this change:
-You must opt-out public routes +You must opt out public routes🧰 Tools
🪛 LanguageTool
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...(NOUN_VERB_CONFUSION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
🔇 Additional comments (2)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (2)
99-111: Code examples are well-structured and comprehensive.
The middleware code examples effectively demonstrate:
- Basic middleware setup with proper matcher configuration
- Route protection with callback functions
- Configuration options for public paths and authorization
Also applies to: 118-129, 136-152, 164-186
79-187: Documentation successfully reflects the increased importance of middleware.
The middleware section effectively communicates its essential role in the SDK v2.5.0, aligning with the PR objectives. The documentation provides clear guidance on setup, configuration, and best practices.
🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
Also discuss limitations about the refreshTokens utility in Next.js
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (3)
81-87: Improve clarity of middleware introductionThe introduction to middleware could be clearer with better punctuation and grammar:
-Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience. +Middleware is used to protect routes in your Next.js app and is a requirement for a seamless authentication experience. -We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. +We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated, they are redirected to log in, and once they have logged in, they will be redirected back to the protected page which they should now have access to. -This means that by default, all routes will be protected. You must opt-out public routes - see [opting routes out of middleware protection](#opting-routes-out-of-middleware-protection) for more information. +This means that by default, all routes will be protected. You must opt out public routes - see [opting routes out of middleware protection](#opting-routes-out-of-middleware-protection) for more information.🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...(NOUN_VERB_CONFUSION)
97-111: Add explanatory comments to middleware configuration exampleThe middleware configuration example would benefit from more detailed comments explaining the matcher pattern:
export default function middleware(req) { return withAuth(req); } export const config = { matcher: [ - // Run on everything but Next internals and static files + // Matches all paths except: + // 1. _next (Next.js internals) + // 2. Static files: + // - html, css, js, json + // - images (jpg, jpeg, webp, png, gif, svg) + // - fonts (ttf, woff, woff2) + // - other assets (ico, csv, doc, docx, xls, xlsx, zip, webmanifest) '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', ] };
1454-1472: Enhance token refresh section structureThe token refresh section would be clearer with better formatting and additional context:
## Refreshing Kinde data -Our middleware will automatically refresh the tokens in your session in the background. +### Automatic refresh +The middleware automatically refreshes the tokens in your session in the background. +### Manual refresh Sometimes, you may want to refresh these tokens yourself. An example of this is when you update Kinde data via the UI or with the Management API. To have these updates immediately reflected in your app, you will need to get the most up-to-date Kinde data and then refresh the tokens in your session. +### Usage To get the most up-to-date Kinde data in your session, use the `refreshTokens` helper function provided by `getKindeServerSession`. <Aside> -**Important!** Due to limitations in Next.js, this will only work in a route handler or server action. +**Important!** Due to Next.js limitations, this will only work in: +- Route handlers +- Server actions </Aside> +### Example ```tsx 'use server' const { refreshTokens } = getKindeServerSession(); const handleRefresh = async () => { await refreshTokens(); } ... <button onClick={handleRefresh}>Get up to date data</button></blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: CodeRabbit UI** **Review profile: CHILL** **Plan: Pro** <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between fb85b0fc8f7235fb6f545caa04e30dbe46c8ca18 and 63e2977b77f8bf9ec1256faac65ecbcc4a36ac86. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx` (2 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 LanguageTool</summary> <details> <summary>src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx</summary> [typographical] ~83-~83: Consider adding a comma. Context: ...atcher. If the user is not authenticated then they are redirected to login and once t... (IF_THEN_COMMA) --- [misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’? Context: ...thenticated then they are redirected to login and once they have logged in they will ... (LOG_IN) --- [grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space. Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ... (NOUN_VERB_CONFUSION) </details> </details> </details> <details> <summary>🔇 Additional comments (1)</summary> <details> <summary>src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (1)</summary> Line range hint `79-1472`: **Documentation updates align with version 2.5.0 requirements** The documentation changes effectively communicate the increased importance of middleware in version 2.5.0, particularly its essential role in token refreshes. The restructuring and additional explanations provide clear guidance for users upgrading to the new version. <details> <summary>🧰 Tools</summary> <details> <summary>🪛 LanguageTool</summary> [typographical] ~83-~83: Consider adding a comma. Context: ...atcher. If the user is not authenticated then they are redirected to login and once t... (IF_THEN_COMMA) --- [misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’? Context: ...thenticated then they are redirected to login and once they have logged in they will ... (LOG_IN) --- [grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space. Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ... (NOUN_VERB_CONFUSION) --- [style] ~190-~190: Try using a synonym here to strengthen your writing. Context: ...p in the Kinde Auth Provider. This will give you access to the Kinde Auth data in your a... (GIVE_PROVIDE) </details> </details> </details> </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (3)
83-87: Add comma for better readabilityThe sentence structure needs improvement for clarity.
-We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. +We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated, they are redirected to log in, and once they have logged in, they will be redirected back to the protected page which they should now have access to.🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...(NOUN_VERB_CONFUSION)
87-87: Fix hyphenation in verb formThe term "opt-out" is incorrectly hyphenated when used as a verb.
-You must opt-out public routes +You must opt out public routes🧰 Tools
🪛 LanguageTool
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...(NOUN_VERB_CONFUSION)
1456-1470: Enhance the token refresh documentationThe explanation about token refreshing could be more comprehensive.
-Our middleware will automatically refresh the tokens in your session in the background. -Sometimes, you may want to refresh these tokens yourself. An example of this is when you update Kinde data via the UI or with the Management API. -To have these updates immediately reflected in your app, you will need to get the most up-to-date Kinde data and then refresh the tokens in your session. -To get the most up-to-date Kinde data in your session, use the `refreshTokens` helper function provided by `getKindeServerSession`. -<Aside> -**Important!** -Due to limitations in Next.js, this will only work in a route handler or server action. -</Aside> +Our middleware automatically refreshes the tokens in your session in the background. However, there are scenarios where you might need to manually refresh these tokens: +1. After updating Kinde data through the UI +2. After making changes via the Management API +3. When you need immediate reflection of changes in your app +To manually refresh tokens and get the most up-to-date Kinde data in your session, use the `refreshTokens` helper function provided by `getKindeServerSession`. +<Aside type="warning"> +**Important Next.js Limitation** +Due to Next.js's architecture, the `refreshTokens` function can only be called from: +- Route handlers +- Server actions + +It will not work in other contexts. +</Aside>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
🔇 Additional comments (1)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (1)
Line range hint 79-1474: Documentation updates align with version 2.5.0 changes
The documentation changes effectively communicate the increased importance of middleware and its essential role in token refreshes for version 2.5.0. The restructuring and rewording make the requirements clearer for users.
🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
[style] ~190-~190: Try using a synonym here to strengthen your writing.
Context: ...p in the Kinde Auth Provider. This will give you access to the Kinde Auth data in your a...
(GIVE_PROVIDE)
| Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Strengthen the requirement statement
The current wording doesn't fully emphasize that middleware is now a requirement in version 2.5.0. Consider revising to make this clearer.
-Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience.
+Middleware is a required component in version 2.5.0+ for handling authentication and token refreshes in your Next.js app. It is no longer optional.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience. | |
| Middleware is a required component in version 2.5.0+ for handling authentication and token refreshes in your Next.js app. It is no longer optional. | |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (2)
79-86: Enhanced Middleware Requirement and Clarity
The new "Set up middleware" section effectively introduces the updated requirement for middleware in version 2.5.0. To improve clarity and adhere to best writing practices, consider revising the sentence that describes the redirection behavior. For instance, instead of:
"If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to."
you could use:
"If the user is not authenticated, they are redirected to log in, and once authenticated, they will be redirected back to the protected page, to which they now have access."Additionally, change “opt-out public routes” to “opt routes out of protection” to correct the verb usage.
Suggested diff:
-If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. +If the user is not authenticated, they are redirected to log in, and once authenticated, they will be redirected back to the protected page, to which they now have access.-This means that by default, all routes will be protected. You must opt-out public routes - see [opting routes out of middleware protection](#opting-routes-out-of-middleware-protection) for more information. +This means that by default, all routes will be protected. You must opt routes out of protection - see [opting routes out of middleware protection](#opting-routes-out-of-middleware-protection) for more information.🧰 Tools
🪛 LanguageTool
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...(LOG_IN)
154-183: Additional Middleware Options and Security Consideration
The "Additional middleware options" section provides a comprehensive example of how to pass extra configuration to the middleware, such asisReturnToCurrentPage,loginPage,publicPaths, and a customisAuthorizedfunction. One minor recommendation is to update the logging inside the middleware callback to avoid potentially exposing sensitive token details. For production usage, it is advisable to either remove or modify the logging statement.Suggested diff:
-export default withAuth( - async function middleware(req) { - console.log("look at me", req.kindeAuth); - }, +export default withAuth( + async function middleware(req) { + // For demonstration purposes only. Avoid logging sensitive token details in production. + console.log("Middleware invoked. Token details:", req.kindeAuth); + },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx
[typographical] ~83-~83: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~83-~83: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~87-~87: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
🔇 Additional comments (3)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (3)
97-110: Middleware Configuration Code Snippet
The provided code snippet for creating themiddleware.tsfile is clear and concise. It correctly importswithAuthand sets up a matcher that excludes Next.js internals and static files. The example clearly demonstrates the basic implementation with no issues.
113-127: Route Protection with Callback Function
This example clearly demonstrates how to use thewithAuthhelper along with an asynchronous callback function that accesses thereq.kindeAuthobject. It effectively illustrates how to customize behavior after authorization. Just ensure that including aconsole.logof token details is acceptable in your documentation context.
131-150: Opting Routes Out of Middleware Protection
The snippet for opting routes out of middleware protection is well structured. It shows how to use thepublicPathsoption to exempt specific routes (e.g.,/blog) from authentication, which is highly valuable for developers. The example is straightforward and communicates the intended functionality clearly.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx (2)
79-106: Enhance API Path Customization SectionThe new "Customising Kinde Auth API paths" section clearly explains how to override the default API path and adjust the sub-paths via environment variables. The examples and instructions are concise and easy to follow. One suggestion is to briefly mention that these customizations support the updated behavior in version 2.5.0, so users immediately understand the context of the change.
1482-1510: Clarify and Strengthen the Refresh Tokens ExampleThe "Refreshing Kinde data" section does a good job explaining why and when you might need to manually refresh tokens. The example using the refreshTokens helper is useful; however, a couple of improvements could make it even clearer:
Consider including an import statement for getKindeServerSession to ensure the snippet is self-contained:
+import { getKindeServerSession } from "@kinde-oss/kinde-auth-nextjs/server";The code sample uses a
'use server'directive and shows an onClick handler on a button. Since Next.js server actions are intended to run in route handlers or server action contexts (and not directly as client-side event handlers), it might help to clarify in a comment that this example is meant to be used as a server action (or provide guidance on how to wire it correctly into a client component).These clarifications will help prevent any confusion about server–client boundaries and ensure that users integrate token refresh actions in a way that complies with Next.js best practices.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx
[typographical] ~111-~111: Consider adding a comma.
Context: ...atcher. If the user is not authenticated then they are redirected to login and once t...
(IF_THEN_COMMA)
[misspelling] ~111-~111: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...thenticated then they are redirected to login and once they have logged in they will ...
(LOG_IN)
[grammar] ~115-~115: The word “opt-out” is a noun. The verb is spelled with a space.
Context: ... all routes will be protected. You must opt-out public routes - see [opting routes out ...
(NOUN_VERB_CONFUSION)
The upcoming 2.5.0 release of the Next.js SDK makes middleware significantly more important - it's now essential for efficient token refreshes.
To signify this, the Middleware section has been moved up from the bottom of the page towards the getting started/configuration section and wording has been changed to describe why it's a requirement.
The middleware matchers have been updated to the new 2.5.0 format as well.
IMPORTANT We should hold off on merging this until version 2.5.0 of the SDK has been released.
Summary by CodeRabbit
Summary by CodeRabbit
New Features
Documentation