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 significant updates to the documentation for the Next.js App Router SDK, specifically focusing on middleware setup and route protection. A new section titled "Set up middleware" has been added, detailing the use of 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. | |
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