prev·log

my log of headbangs, when Next resulted in prev ^†

# releases
Aug 20, 2025
Releases & Versioning

I’m delving into personal projects way more than before, and I started using Renovate extensively for keeping my dependencies up to date. It saves tons of time and effort to deal with this tedious task.

And man, do I get goosebumps every time a new Next.js release pops up?!

I’d expect it to be a walk in the park, and yet…
- amount of changes - Some releases contain just a few changes, but the “real ones” would make you cry. v15.5.0 contains 234 core changes, and 215 misc changes. Good luck there’s something that won’t affect you.
- canary piling / versioning - They mix canary releases along regular ones. It seems the team aims for “the next big release” right from the last of this kind, but they don’t bother with semver that much.
  
  So after v15.4.1, they started having v15.4.2-canary.1. Which does not mean the next “official” release would be v15.4.2, oh no, it turned out to be v15.5.0!
- backporting - Meanwhile, they make other releases, I guess with important fixes. Something like “not quite a release, but still”. After v15.4.1 there’s v15.4.2 saying:
This release is backporting bug fixes. It does not include all pending features/changes on canary.
- no release notes - They didn’t configure any release notes properly, so you never know what you’re getting. You have to go to github and patiently read the 6 screen “summary” of what they did, most of the time without understanding a word because of internals.
There’s nothing utterly complex here - people have figured it out ages ago. semver exists for a reason. Continuous delivery is blooming. Astro is shipping things in such a small and thoughtful way it’s a pleasure knowing things will work! Just check the confidence level of Renovate - even 28 days after a new Next.js release, it’s still “neutral”, while Astro’s are beaming green a few hours later!

I’m sure maintaining this monster is not an easy task. Yet, there are simple steps to improve DX tremendously, and I expect a company like that to tackle them.
# patching-lockfile
Feb 5, 2025
Patching lockfile

At some point builds started to fail, and I’m waking up to this:
```
Found lockfile missing swc dependencies, patching...

error This project's package.json defines "packageManager": "yarn@npm@10.8.1".
However the current global version of Yarn is 1.22.22.
```
Plus a bunch of errors following this one (which was on line 480), regarding yarn, build steps, etc. This particular project has "packageManager": "npm@10.8.1" inside its lockfile, so I was thinking about some versioning problem, or dependency requirement… There’s nothing yarn related in our project, and I was lost!

So it took me a while to carefully read this one: yarn@npm@10.8.1. For some reason, Next, trying to patch my lockfile, ended up adding yarn@ in front of my npm@10.8.1 line. Which makes it think it needs yarn, version npm@10.8.1, which obviously is not a good yarn version…

There’s a list of possible fixes about it: https://nextjs.org/docs/messages/failed-loading-swc
# @next/mdx
Jan 4, 2025

Installing @next/mdx

As our website has a lot of downloadable (pdf) legal documents, our team decided to use md for a content source. That meant we’d need some library to parse and display that content on our static pages, looking the same as the pdf file.

For some reason @next/md is not fully compatible with our project - TS was complaining inside the Next config. The moment I’ve searched for issues and found this one was the moment I decided I’d switch to something else.

I’m so tired of inconsitencies that I didn’t even try to dig deeped. It took me less than a minute to install react-markdown and call it a day.
# react19-rc
Oct 24, 2024

RadixUI & shadcn/ui not working

On 21st of October, Next.js 15 was officially released, yay! 🎉

Among the release notes there’s this note:

In version 15, the App Router uses React 19 RC

Depending on a release candidate? 🤔 How bad can it be?

Although React 19 is still in the RC phase, our extensive testing across real-world applications and our close work with the React team have given us confidence in its stability.

And that’s probably true. What wasn’t accounted for are the numerous dependencies on react: ^18.x all over the internet. Including radix-ui/icons, which makes shadcn/ui unable to install properly. And sadly, we were using those 😔

It took a good full week to fix the issue. But more libraries were affected: NextUI, zustand, heroicons, Material UI and I’m guessing many more.

All of that isn’t directly Vercel’s fault. But it kind of is, isn’t it?
# catch-all-segments
Sep 30, 2024

Return an Array in generateStaticParams

When you’re using the Catch-all Segments feature, you must return an array of params in generateStaticParams, even though it should always contain a single entry.

And it kinda makes sense if you really think about it:

Route: pages/shop/[...slug].js

URL: /shop/a
Params: { slug: ['a'] }

URL: /shop/a/b/c
Params: { slug: ['a', 'b', 'c'] }

In this case, slug is an array, as it might contain multiple URL segments. But when using generateStaticParams, you are basically generating params for every single page.

And yet, instead of items.map((item) => ({ slug: item.slug })) you’d go for items.map((item) => ({ slug: [item.slug] })), so it goes with the catch-all paradigm of “might be more than one”. Another case where things mix up too much. I guess better documentation might help.
# utf-8
Sep 23, 2024

Revalidation Encoding

I’m developing a website where the URLs include non-latin characters. And I need to revalidate certain pages (or even tags), in order to use the Incremental Static Regeneration (ISR) feature. Turns out those must be encoded before revalidating, or it throws tremendously ambiguous error.

It sounds a bit logical for the paths, but why the tags, as those are completely internal?!
# utf-8
Sep 3, 2024

Non-latin page names

I started a new project, where I need URLs to contain non-latin characters (like /тест, which is /test in Cyrillic). The page’s file name (using AppsRouter) is what determines the URL.

Well, it seems there’s a four-and-a-half year old (still opened) GitHub issue about that. Next doesn’t like non-latin characters, as the router isn’t dealing with decoding good enough.

A simple workaround is to name your files with encoded values. So тест.tsx becomes %D1%82%D0%B5%D1%81%D1%82.tsx. Awesome DX! 🎉

I’ve ended up naming my pages in English, and then using Next config rewrites, where I encode my URLs.
# middleware
Aug 16, 2024

Middleware not working because of instrumentation

This one was completely my fault, but it was deeply burried. Middleware was not working. Regardless of what I put inside the file, nothing happens. And I needed it because I needed the server to know what’s the current URL on the server side (which I couldn’t implement back then) 😂

There were no errors at all! It just wasn’t working.

I started carefully reading all the logs, and I saw a warning saying that it cannot acccess some browser related APIs. After a lot of tinkering and deleting anything that is browser related (so I can catch the issue), I ended up deleting chalk. Which is coloring the output of a log.

And since we were using it in many places, the logger util ended up in the instrumentation file, so that I can pretty-print what branch we’re running on during startup.

And because of that error, which was silently devoured from Next’s internals, middleware couldn’t boot properly.

p.s. I ended up using picocolors.
# current-url
Mar 20, 2024
Get the current URL server side

It caught me completely off guard! One would think the server should easily know what’s the current URL it’s serving, right? So you could do some stuff based on it.

Next doesn’t agree. Most of the system does not know about the request context at all.

The solution? Bring up the heavy tools - intercept and add custom header!
```
// middleware.ts
export function middleware(request: NextRequest) {
  return NextResponse.next({
     request: {
        // New request headers
        'x-pathname': request.nextUrl.pathname,
     },
  });
}

// app/some/where/page.tsx
import { headers } from 'next/headers';
export default async function Page() {
  const pathname = headers.get('x-pathname');
}
```
Unfortunately this comes at a huge price - every time you use headers, it breaks caching, because it’s a dynamic function! As of now, I haven’t seen an easy way around it.

Honestly, this one made me a bit sad. It’s okay for my use case, but it’s just awful…
# static-prop
Feb 8, 2024
revalidate prop literal

You want to configure a single page of yours to use time-based Incremental Static Regeneration? Sure thing, just define how often you’d like your new page to be regenerated:
```
export const revalidate = 3600 // invalidate every hour
```
You want it every day, but you dislike how 86400 would look like as value? Three days (259200)? 604800 doesn’t ring a bell? Okay, how about this:
```
export const revalidate = 60 * 60 * 24 * 7; // a week in seconds
```
Well, well, come on, don’t be greedy! That is too much! From the Route Segment Config’s doc about the revalidate prop:

The revalidate value needs to be statically analyzable. For example revalidate = 600 is valid, but revalidate = 60 * 10 is not.

At this point I literally started wondering who’s developing this framework and what their problem is! It took me a good few hours to get to the docs.

And it sounds like someone is scraping the code as text and then figuring out what he value is. I get it - there are multiple environments this can run in, and sometimes compiling the code would require more time and resources. But that’s withing the App Router! How hard would it be to have page.config.ts along your page.ts file?! Why on earth would someone do such a thing?

Some pieces of this software are incredible and powerful. Others feel wrong on so many levels it’s amazingly hard to describe. And it’s just sad.
# get-cached
Jan 16, 2024

Cached GET Response

I’ve been using Next mostly on the front-end side until now, and I wasn’t prepared for this 🤯 It wasn’t long until I realized my GET endpoints were always returning the same data for some reason. And it turns out it’s documented that Route Handlers are cached by default when using the GET method with the Response object. There are some weird hacks like using cookies and headers, but that’s just too much.

note: this has changed since then
# config-js
Jan 11, 2024

next.config is JS only

Since the initialization, I’ve been using TypeScript for the entire project. And yet, as it turns out, the very basic next.config file can only be in JavaScript.

So what, you’ll ask? Well I wanted to have some navigation items that are using rewrites, which are part of the config file. So I don’t want to have duplication of code, especially when dealing with links. But mixing TS and JS is still a pain in the ***.

Why would someone support TS all over the place, and not in its main config file? Surely it needs transpilation, but how hard could that be?