Updating to Next.js 15

Makerkit was originally built on top of Next.js 14. However, with Next.js 15 being released, we've updated the boilerplate to align with the latest version.

This means there will be a few changes to your codebase that you may need to apply or merge from the latest version of the boilerplate.

Fortunately, the API hasn't had large break changes, so the migration should be relatively straightforward. However, there are some changes that you may need to make, and you'll need to do them manually.

This documentation will only guide through what we need in Makerkit. However, for a more comprehensive guide, you can refer to the Next.js documentation and Makerkit's own guide to updating to Next.js 15.

The changes in Next.js 15

Here's a broad overview of the changes:

1. Update Next.js version: Update the Next.js version in the various packages
2. Update Next.js configuration: If you've modified the Next.js configuration, you'll need to update it to align with the latest version
3. Dynamic Params are now Promise-based: Probably the most significant change is the introduction of dynamic params. This means that you'll need to update your code to use promises instead of syncronous functions when accessing cookies, headers, and query params and segments.

The kit also added some other general improvements that regard linting and formatting, therefore some merge conflicts may arise. However, these are less important and you can simply resolve them manually by accepting your own changes.

The migration make take anything between 5 minutes to an hour depending on your codebase. Believe me, it's still a lot less than the changes and research I did on my side! 😅

Update Makerkit to the latest version

To update Makerkit to the latest version, you can run the following command:

git pull upstream main

This will update all the packages in your project to the latest version. You may need to merge conflicts manually.

Then, install the packages again:

pnpm i

Updated Promise-based dynamic APIs

The large majority of the changes in the Makerkit's Next.js 15 update are related to the change of dynamic APIs into Promise-based APIs.

This means that you'll need to update your code to use promises instead of syncronous functions when accessing cookies, headers, and query params and segments.

For example, where you before had the following code:

const cookie = cookies().get('session');

You will now need to use the following code:

const cookieStore = await cookies();
const cookie = cookieStore.get('session');

The same applies to headers, query params, and segments.

React Compiler

The React Compiler is set to be off by default, however, you can enable it by setting the experimental.reactCompiler flag to true in your next.config.mjs file.

Dev Mock Modules

Since we don't need to compile all the packages during development, we make sure to alias them to the mock modules, therefore speeding up the development compilation (eg., page transitions, hot reload, etc.).

We use Turbopack's alias feature to achieve this, in the next.config.mjs file.

There's not too much to it, but if you're curious, this is why we have added the code loading the mock modules.

Dependencies Updates

All the dependencies have been updated to the latest version. This includes notable changes such as Radix UI, Stripe

Conclusion

Updating Makerkit to Next.js 15 is a relatively straightforward process. However, you may encounter merge conflicts, and you'll need to resolve them manually. In addition, you will need to update your code to use promises instead of synchronous functions when accessing cookies, headers, and query params and segments.

Please head to our Discord server if you have any questions or need help with the update process.