fix: resolve Next.js 15.5+ route handler type compatibility issues

[asionesjia]

Summary

This PR fixes TypeScript compatibility issues with Next.js 15.5+ route handlers while maintaining backward compatibility with Next.js 14.

Problem

In Next.js 15.5+, the type checking for route handlers became stricter, causing the following error:

Type error: Type 'typeof import(".../route")' does not satisfy the constraint 'RouteHandlerConfig<"/...">'. Types of property 'GET' are incompatible. Type 'NextHandler' is not assignable to type '(request: NextRequest, context: { params: Promise<{ ... }>; }) => void | Response | Promise<void | Response>'. Types of parameters 'req' and 'request' are incompatible. Type 'NextRequest' is not assignable to type 'BetterStackRequest'. Property 'log' is missing in type 'NextRequest' but required in type '{ log: Logger; }'.

Solution

The issue was in the type signature of the withBetterStack function. Previously, it was incorrectly returning BetterStackRouteHandler when wrapping route handlers, but it should return NextHandler since:

1. Input: BetterStackRouteHandler - The handler written by users that expects BetterStackRequest (with log property)
2. Output: NextHandler - The handler that Next.js can use, accepting standard NextRequest
3. Purpose: The wrapper adds the log property internally, bridging the gap between the two types

Changes Made

• Separated BetterStackRouteHandler (user-facing type) from NextHandler (Next.js-facing type)
• Fixed the return type of withBetterStack overload from BetterStackRouteHandler to NextHandler
• Updated withBetterStackRouteHandler to properly handle the type transformation

Testing

• ✅ Tested with Next.js 15.5.3 (latest)
• ✅ Tested with Next.js 14.x for backward compatibility
• ✅ Updated example/logger to Next.js 15.5.3 to verify the fix

Breaking Changes

None. This fix is fully backward compatible.

Related Issues

Fixes compatibility issues with Next.js 15.5+ strict type checking for route handlers.

[asionesjia]

I reverted the version update for example/logger because it conflicts with the next version in logtail-nextjs. This results in an error in npm, though it works fine with pnpm.

I didn’t attempt a full dependency upgrade yet, since many dependencies are still on older versions and I’m not certain whether upgrading everything now would cause additional issues.

Since this bug is blocking builds on Next.js 15.5.x, it would be great if we could prioritize merging this fix first, and handle the dependency alignment in a follow-up.

[PetrHeinz]

Hi @asionesjia and thanks for the PR 🙌

We're tracking the issue of incompatibility with the newer Next.js version internally, and while I can't provide any ETA just yet, I'll try to make sure this gets prioritized to unblock builds based on v15.5.0 or higher without relying on a forked package.

Thanks for bringing it to our attention and suggesting a specific update 🙏

[Mark-Life]

+1

[willium]

+1

[PetrHeinz]

Thank you for your patience 🙏

We've been planning on tackling the Next.js 15 and 16 compatibility for quite some time, it should be released as v0.3.0 🚀 You can see the work in progress in #31

[PetrHeinz]

Happy to report the v0.3.0 has been released on NPM 🚀

There are minimal changes in the usage which you can check in our docs. Hope it helps 🙌

I'd be happy to hear your feedback!