Report from Nuxt auto-import pitfall

We all have been there, right? Spending frustrating hours trying to solve a mysterious bug. Nothing works and it doesn't even make sense. Until it suddenly does. You realize what was wrong. And the solution actually works! Such a mix of happiness, relief and pride - you are still worthy!

Last time I experienced this was yesterday. And I want to share the story. Because I think the reason is quite interesting. It is related to Nuxt and the specific behavior of this JS framework. If you are not familiar with Nuxt, you might not be so amused. But if you are a fellow Nuxter, this might help you someday.

To make it quick, I was playing with Nuxt Content. This module takes your Markdown-formatted files and does most of the hard work to display its contents on your website. With the latest version, you only need to:

1. Put your .md sources into /content folder
2. Define the document collection
3. Use <ContentRenderer> to display them

This is not that hard and if you're interested, here is a demo.

I needed to go one step further. I am from Czechia and here leaving a single-letter word at the end of the line is considered a typography error. Placing   everywhere manually is pretty annoying. So I created a package for automated replacing. My goal was to integrate this with Nuxt Content.

Sounds harder than it is. Nuxt Content is providing a hook where you can augment your custom text processing with ease. So I did. And it worked in dev. I moved forth and deployed the solution. Waited for the Netlify automation to build and deploy the site. And...my site appeared empty with no articles!

It took me a while to figure it out. The first problem was that the 'content:file:beforeParse' hook where the Markdown files are processed happens quite early in the app initialization process. Looking for logs when you are navigating to the page with content was already too late. Second, worse - the problem actually was in the logging itself.

What happened? I am using unjs/consola for enhanced logging. The way of injecting the logger object into the file is to define it in /utils/consola.ts and export it from there. Because Nuxt uses auto-imports, this should ensure it is automatically available everywhere in my app. Really cool stuff, one of my favorite Nuxt features along with automatic file-based routing.

Except it didn't work this time.

When I finally reached for the error message via old-fashioned console.log, it said: "log is not defined". I am not 100% sure with all the details under the hood, but the Nuxt Content hook simply occurs before Nuxt is properly initialized and the auto-imports resolved.

The solution was a one-liner:

import { log } from './consola'

And everything works again. My articles come from .md files and are automatically treated to prevent single-letter words at the line ends.

Lesson learned from this is that Nuxt auto-imports might be a double-edged sword. Most of the time they're making your dev life easier, but can bite back occasionally. This is not meant to discourage you from relying on this feature, just to show an example of what might go wrong.