SDK Auto-Configuration for NextJS

📣 Next.js Auth SDK 3.1.0 Release 🎉

There were several enhancements to the Next.js Auth SDK with this release. Please refer to the GitHub README for updated documentation and details.

Below is a summary of all changes:

• The all new SDK auto-configuration functionality is now available for the Express Auth SDK. It supports lazy auto-configuration. Auto-configuration is enabled by default and will fetch missing configuration values from the Wristband SDK Configuration Endpoint when any auth method is first called. Manual configuration values take precedence over auto-configured values. Set autoConfigureEnabled: false in the AuthConfig to disable.

  🚧

  Auto-Configuration in Edge Runtimes

  While auto-configuration works well in Node.js runtime environments, manual configuration is strongly recommended when using Next.js Edge Runtime (Edge API Routes, Middleware, and Edge-rendered pages) due to the following limitations:

  • Cold start latency: Auto-configuration requires an API call to the Wristband SDK Configuration Endpoint on every cold start, which can impact response times for authentication flows in Edge Runtime.
  • No persistent memory: Edge Runtime instances don't maintain in-memory caches between requests, causing the SDK to refetch configuration data on every invocation.

  For production Next.js applications using Edge Runtime, you can set autoConfigureEnabled: false and provide all required configuration values manually. This is especially critical for authentication middleware that runs on every protected route.

• The AuthConfig class can now take an optional tokenExpirationBuffer configuration. This buffer time (in seconds) gets subtracted from the access token’s expiration time. This causes the token to be treated as expired before its actual expiration, helping to avoid token expiration during API calls. The default value is 60 seconds if not explicitly configured.
• The CallbackData and TokenData types now return an expiresAt field. This is the absolute expiration time of the access token in milliseconds since the Unix epoch. The tokenExpirationBuffer configuration is accounted for in this value. Developers no longer need to calculate this value in their own app code.
• The loginStateSecret config is no longer required. If not provided, it will default to using the client secret. For enhanced security, it is recommended to provide a value that is unique from the client secret. You can run openssl rand -base64 32 to create a secret from your CLI.
• The LoginConfig class for the login() function now supports a returnUrl field. If a value is provided, then it takes precedence over the existing return_url request query parameter. This new login config provides the same functionality as the existing query parameter approach.
• The LogoutConfig class for the logout() function now supports a state field. This is an optional value that allows you to preserve application state through the logout flow when redirecting to the Wristband Logout Endpoint. If provided, it will be appended as a query parameter to the resolved logout URL. Maximum length of 512 characters. This is useful for tracking logout context, displaying post-logout messages, or handling different logout scenarios.