1. Why project documentation is so important.

2. How to create and roll a new Docs app on top of Nuxt.js Content Module.

3. How to arrange it inside the Turborepo.

4. Docs application internals:

   1. layouts,

   2. styling,

   3. components,

   4. utilities,

   5. reusability,

   6. scaling.

5. Advanced techniques of managing data.

6. How to add Docs to existing Nuxt.js project.

This will be a series, split into two or three articles, With this one we will cover the very basics, and with another one we will dive a bit deeper, covering more advanced stuff.

I have an anecdote at first.

I’ve been building an ecosystem of packages for a framework - one of those side projects that grew organically over time. One package was almost done, just needing a few final touches. But before wrapping it up, I switched my focus into another one. Since this was a side project, progress happened in bursts over several weeks.

When I finally returned to the first package, I hit a wall. How did this thing even work again? The logic that once felt so obvious now seemed like a puzzle. Hours went by as I dug through the code, retracing my own steps like a detective trying to solve a mystery left behind. Eventually, I figured it out, the code quality was good enough - but not without frustration. If I had just taken a few minutes to document the structure, my key decisions about the internal APIs, and intended next steps, I could have saved all that lost time. Bummer.

The lesson was clear: when you don’t document your work, you’re leaving future-you a mess to clean up. Whether it’s in the code or separate documentation, you must write it down. Your future self - and anyone else who touches the project - will thank you. Without documentation, even your own work can feel like a black box after a (just) few weeks away. Again, a few simple notes on structure, key decisions, and next steps can save hours of frustration and make your project easier to maintain, extend, and collaborate on.

If it’s worth building, it’s worth documenting!

I hope this story resonates with you at some point and encourages you to pay more attention to documentation. Since we've started this discussion, let's frame it within our current context: a newly created Nuxt 4 app set up in a monorepo. This is an excellent opportunity to launch a fresh Nuxt app and explore the full potential of Turborepo's capabilities.

OK, so the recommended way to build documentation on Nuxt is by using its official Content Module, Nuxt Content (NC). It provides a comprehensive set of tools, including components, composables, and extensibility utils, making it suitable for various content-driven applications such as blogs, landing pages, and, of course, documentation. You can initialize it along with your current, already-existing project and/or build a fresh, independent application, which we’ll try to do here. No worries, at the end I’ll describe how to achieve it also with a regular Nuxt app. Let’s go!

Go to your apps/ folder and create a new one, named docs, or whatever you like. Inside this folder we need to initialize a new Nuxt application, we can do it by using nuxi (here you can read more about nuxi). Use this command.

pnpm dlx nuxi@latest init

(remember? we’re using pnpm now, for everything, if possible 😜)

OK, new application will be initialized. Before we move further we need to clean a bit around common internals. Here - at first - I have ESLint in mind. You can install it along. To do this jump into the apps/docs/ context. There run the installation procedure described here. However, at this very moment we will face doubling the same dependencies and configuration. That’s not prefect situation. This is where the magic of a Turborepo steps in.

Inside packages/config/eslint folder create a new nuxt.base.mjs file. There paste the Nuxt-related configuration from the apps/web/ app. Like that.

Just after expose this file through your package.json.

Now as we have our common Nuxt ESLint configuration exposed from the @yourmonorepo/eslint-config package we can use it along with both, apps/web and apps/docs applications. Use it like this.

Yeah - magic of monorepo, you can share lot of stuff the same way, just like that.

💡 Useful Tip

From the root of your monorepo, inside the package.json file you can add dedicated scripts to run just one app at a time - if you don’t need them going all together. Do it like that.

Awesome! Let’s get back to the main topic, our Docs. I’ve mentioned already that the best way to build Docs on Nuxt is to use their official Content Module, which we will execute right now. Inside your Docs (apps/docs) app please run this command.

pnpm add @nuxt/content

Next, add new module @nuxt/content to the Docs nuxt.config.ts file.

Two more things, before we move on - as we’ve decided to work within the context of Nuxt 4, let’s rearrange our directory structure, as shown and described here.

Share vue.house

It would be also beneficial, since we are working within the monorepo environment, to define dedicated port for our Docs app. Add this to your Docs app nuxt.config.ts file.

{
  ... rest of the config
  devServer: {
    port: 3010,
  },
}

Great, now we can proceed. Please, inside the apps/docs/ folder create a new configuration content.config.ts file for the NC Module. Like for Nuxt itself NC also need a dedicated configuration. Inside this file define the initial, very minimal configuration. Add collections object and define it’s name by custom key, then use the defineCollection macro function to properly establish the content collection.

Before we move forward I’d like to highlight the key mental model that is crucial for working efficiently with Nuxt Content. The most important thing to understand is that you're still working with a regular Nuxt application, meaning you can do everything you would in any other Nuxt project. The NC simply adds extra capabilities for reading, rendering, and managing local content written in markdown-like formats. The best way to think about it is as a content database that needs to be handled within your app. You’ll still need pages, components, styles, and logic to properly display and organize your content throughout the application.

The approach to building content applications it’s a bit different that it was within the previous versions. Right now you’re starting with a blank and empty app that will require building overall UI and presentation, which means it has to be covered by you, as a custom implementation (for your company i.e.). You have second option though, using one of the predefined, prebuilt templates. Will get there in a moment.

Perfect, let’s get back to our configuration file. What you can see here (actually, up there) is a definition of our content collection. By default NC will read data from the /content folder, so when you’ll use a dedicated utility to fetch content data, each file will be read and transformed to a dedicated format. By defining type you can select rather it will be a paged dedicated format or raw data one. It might be important for you when you’d need to deliver some custom data structures, it’s more advanced topic though, that we can discuss soon. Finally, by defining source you can point the exact path of the collection source and the files format to be read.

Time for some actions - let’s add a test content. Inside the content/ folder create a new file /content/index.md. Put there this simple code.

---
title: Home
description: Test Home Page
---

# Home
Test Home Page

OK, from that moment you may see some ESLint warnings in your IDE, shown along with the code. In fact, this is a dedicated MarkdownLint added to the NC. Here you have two options to handle these warnings. You can correct the code (obviously, daa), or manage the markdown linter rules from a dedicated file. To do it create a new .markdownlint.json config file inside the root folder of your Docs app. From here you are able to structure the rules for linting your markdown code. So my suggestion here would be to not improve the code syntax and add this notation.

You should see that warnings are gone. You can define your own custom rules on top of this guidelines, or just follow the default, predefined ones. Up to you.

Now, as we’ve defined our very first content file let’s go and display it. Jump into the app/index.vue file and add this code inside.

Check out your console now. You should see the ref (dosc) object with your content data. Digg, check out what’s inside. You’ll get there an array with the parsed index.md file data that we’ve just created. It will be located within the body object in which you will get the structured value of the content and the table of contents (toc) additional object, that will provide you links for your page navigation. You can decide how deep it should parse the document. By deep parse I mean what level of the document headers should be included within this structure. You can decide about that by defining content configuration within your nuxt.config.ts file. This is because you can still have your content along with the main app, also content configuration might be lined with the Nuxt configuration itself. So this is how it should looks like.

On top of that, when you’ll use h3 hading level (### Header) inside your markdown files it will be included with the toc object, provided by the content fetching utility.

Alright, so as we’ve fetched our content, now it would be ideal moment to display it along with the page. To do so you need to use <ContentRenderer> component. Along with the code of our page it should looks more less like that.

Right, let’s unpack this. Firstly, look at the line 11, where we have already defined content data fetcher. We’ve changed one thing here, now it’s used first() method, not all(). That’s because queryCollection utility with all method chained (as name suggests) fetches all of the pages from the content collection. It’s fine, however to render it properly we would need to iterate over the results, which means to use v-for on top of the <ContentRenderer> component. Also, we don’t need to render all of the pages as one. To be more precise with defining which page you’re actually intended to fetch you can use other methods like select() or where() (more about here).

Next, we have simple computed property containerIsEmpty that will check if the page data even exists and will help us to display proper content along withe the page and its template.

About the template. We’ve added <ContentRenderer> component where fetched data was passed; through the :value property. Additionally we have the condition that is handling either it should show the content or “empty page” placeholder.

Enough talking. You should now see your content rendered on the index page. You should see something like this. Is it there? Yeah? Great!

By default your content will be rendered with the prose components. What are they? Prose components are replacements for HTML native typography tags. Prose components provide a simple way to customize content UI. You can replace them also with your custom ones. What’s more important Tailwind CSS supports this solution as well, improving your typography a lot.

Share vue.house

It’s also noticeable that the H2 heading was rendered as a link. It’s like that because this must be an anchor for the navigation. ID(#id) will be added automatically so navigating, as well as linking to a certain content portion/section will be much easier. There is an option to disable it tho. You can achieve that by defining which heading should be rendered as a link within the nuxt.config.ts file.

Before we step into the second post, and some more advanced stuff I would like to initialize the core of that build - the Docs content. Of course, any intro/landing page will be welcomed, but the most important thing for us here had to be the Docs.

Inside the content/ directory (we’re still in the apps/docs/ context) create a new one called docs/, inside of which add new index.md file. Put the some test content, it can be even the same as for the content/index.md. OK, just after you need to add a new collection inside the content.config.ts file. Something like this.

This way our data fetcher, defined inside the pages/index.vue component will fetch also content from the docs/ folder. But hey, we don’t want that! We don’t need docs content on the landing page. Right? Well, to avoid this kind of behavior we can exclude it from content collection. Do it like that.

That’s it, now landing page data will be only restricted to what we have inside the main container. Of course when you’ll add more data like docs/ there will be a need to define additional rules for them, but you can proceed adequately.

OK, we can stop here. With another post I’ll cover templates and overall visual aspect of content presentation. If you don’t want to miss it, and you’re not a subscriber yet please join - it’s free, you don’t need account or registration. I promise! Thanks in advance, Lukas. Enjoy!

Subscribe now

Please let me know how you find this article. What I can improve?

As for now - to me - a natural way of setting up a new application environments is to put them into the monorepo surroundings. What for you’d ask?! Let me describe you a couple of potentialities where it can be super beneficial for you and your future development process.

Multiple Applications

Let’s say you start with a single, small Nuxt app, happily living in its own repository. But as time goes on, the app grows. New features, dependencies, and complexities start piling up. At some point, you realize that to properly document everything—its structure, API, and best practices - you need dedicated documentation.

Now, mixing that documentation directly within your main app’s codebase? Not the best idea. Instead, you decide to create a separate Nuxt-powered documentation site using the Nuxt Content module, generating a static site for all your docs.

But here’s the catch: your original app is dynamic - it’s not meant to be static, and you don’t want to introduce unnecessary complexity by juggling different rendering strategies in the same project.

And that’s where a monorepo makes perfect sense. You keep both applications close but separate, maintaining clear boundaries while still benefiting from shared dependencies, streamlined development, and a unified workflow. Sounds like a solid reason to go monorepo, right? Let’s go further.

Shared Configuration

Now, imagine both apps living together in a single repository. While they serve different purposes, they share a lot in terms of structure and configuration - things like ESLint, Prettier, TypeScript, and even Tailwind. Duplicating these configurations across both apps? Not ideal.

This is where a monorepo shines. Instead of maintaining separate, nearly identical setups, you can create shared packages for common configurations and utilities, making them easily reusable across both apps. This not only reduces duplication but also keeps everything consistent and easier to maintain.

With a monorepo, you gain efficiency, better organization, and a cleaner development workflow - all while keeping your apps close, but neatly separated.

Nuxt Extensibility

Finally, let’s talk about Nuxt’s extensibility system. For years, Modules have been the go-to way to extend Nuxt applications with additional functionality. Traditionally, we could place them directly inside the modules/ directory of a project, but in most cases, they’ve been distributed as external npm packages, maintained by the community.

Now, with the latest updates, the Modules API is explicitly designed for building external packages rather than keeping them inside the core application code. In fact, even the Nuxt team recommends placing them as packages within a monorepo.

The same thing goes for Layers - Nuxt’s approach to micro frontends. These "mini-apps" extend your main Nuxt application and are inherently structured to be packaged separately. Their architecture naturally fits within a monorepo, and they can even be published as standalone npm packages if needed.

By embracing a monorepo setup, you’re not just organizing your project better - you’re aligning with Nuxt’s best practices for scalability and maintainability.

Not convinced yet? Let me introduce you some of the great Turborepo capabilities, as it might be the best choice out there to handle monorepos.

But first - why Turborepo? After all, there are other solid alternatives, right? Well… not quite. Take Lerna. It’s been around for a long time, well-established in the dev community. But over the years, as technology evolved, its performance didn’t keep up. Lerna was primarily designed for managing package-based monorepos, rather than a mix of packages and real applications. Eventually, it was abandoned by its author and later acquired by Nx, rewritten with its engine involved. Now, if you check its GitHub repository, you'll notice that development activity has significantly slowed down - a bit of a bummer.

Share vue.house

Then there's Nx - a powerful, feature-packed tool. It’s huge, advanced, and highly capable, but it's more geared toward enterprises rather than lean startup projects or smaller teams. Not ideal. Finally, there are some tools from MS, and/or Amazon, it’s hard to think about them seriously since they’re an internal enterprise solutions. So, where does Turborepo fit in? Let’s see what it brings to the table in comparison.

Why you should pick Turborepo?

1. Caching. It has great (quite advanced) caching system that is capable to speed-up development process significantly. Once a task is executed (like building, linting, or testing), the results are cached, meaning future runs can be near-instant if nothing has changed. So imagine that you have co-existing packages powering your application (Nuxt module), you don’t need to build them every time when you’re building your main app. Turborepo will provide cached already-built packages for your final execution. What’s more interesting you can even have remote caching, thanks to which packages can be shared with your team. ✨

2. Parallel Execution. You don’t have to wait for a single process to finish - you can run multiple processes simultaneously. And to avoid getting caught in dependency traps, you have pipelines to manage execution efficiently.

3. Pipelines. You can design pipelines for any part of your development process. Whether it's building, running apps, or managing packages, you have full control over execution order. You decide which tasks should run first to provide the necessary resources for other parts of your monorepo.

4. Polymorphic Nature. Unlike Lerna or Bazel, Turborepo isn’t just built to manage packages - it’s designed to deliver and integrate those packages directly into your applications, making them the primary source and backbone of your system.

Historical Outline

The project was initiated by Jared Palmer, who identified limitations in existing monorepo ecosystem like Lerna (daa), especially concerning performance and scalability. He aimed to create a tool that could handle complex monorepos with advanced features. Initially, Turborepo was developed using Go. However, to leverage performance benefits, the team transitioned to Rust, resulting in significant improvements in speed and efficiency. In December 2021, shortly after its release, Vercel acquired Turborepo, integrating it into their suite of developer tools to enhance performance and scalability for frontend applications.

OK. If you’re still not convinced, maybe you’ll just give it a quick try? I can promise you that the setup and workspace organization will be fast and easy. Additionally, on top of our starting guide, you’ll be ready to go, building with your new and shiny environment on top of Turborepo. Deal? Let’s go!

Firstly, let’s make a small rearrangement within your root directory. Create there two new folders: packages/ and apps/. Inside apps/ create a new one called web/ - here will be the best place for your main Nuxt app, so please move it there.

In the root please leave the .gitignore file, you can add to it turbo-specific folders that will held the cache and configs.

# turborepo specific
.turbo
.history

# pnpm specific
~
~/*

OK, let’s initialize the main package.json file. Use pnpm for that.

pnpm init

pnpm will also need to have a workspaces.yaml file to inform Turborepo where you’re actually storing your apps and packages. Create it inside the root folder and place there this code.

packages:
  - 'apps/**'
  - 'packages/**'

Then you need to install the thing. Run this command.

pnpm add -D turbo

Now, when the turbo is already installed, it needs a configuration file. Please, inside your root directory create a new file turbo.json. Insert there this content.

What we have here? $schema is the internal Turborepo set of configs so you can leave it as it is. Then you have tasks object. This is where you’re defining your processes and pipelines. Name of tasks should be corresponding with the name of your scripts, so if you’re using script dev to run your development process define it like that, same for building and/or linting. On top of this Turborepo will scan all of your apps and packages for package.json files and will run the dev scripts from them, parallelly. Each task can have its own pipeline defined to be processed in the desired way along with the other components of your monorepo. Here you can read more about defining it/them step by step.

By defining outputs you’re telling Turborepo that should store this exact distribution folder and reuse it within the next execution. You can always force the rebuild without/leaving cached resources.

Now, we need to add these tasks to our main packege.json file.

One more thing that you need to do is to move the lint-staged configuration from the Nuxt folder to the main/root one. Now you’ll be linting all of the apps and packages within your repository so you have to define how scan them all together. Do it like this.

Alright, I believe you can test it now. In your root directory run this command.

pnpm run dev

What you’ll see it will be a Nuxt app process running straight from the main scope.

yourmonorepo/web:dev: Nuxt 3.15.4 with Nitro 2.10.4

Awesome! You now have yourmonorepo (scope name, the name of your main package, please change it) with Turborepo ready and going. Along the way, while we will develop our codebase adding a new apps and packages we will be extending Turbo configuration and how it behaves. If you don’t want to miss any of the future publications please subscribe to stay up to date.

Subscribe now

Last but not least what we can do here - it can be a great reference for the further improvements - will be creation of a global config for ESLint. Interested?

Inside your packages/ folder create a new one: config/, and inside of it add a new one named eslint/. Now we need to initialize a new package configuration. Run the pnpm init command. New package.json file will be created. Inside you can define something like this.

OK, as you can see we’re referring here to the index.base.mjs file. We don’t have it so let’s create one. Inside newly created please add this content.

You’ll notice that it’s almost the same config that we’ve had for our Nuxt application. That’s right, we’re globalizing it so common parts were moved.

Additionally, from the Nuxt package please move the dependencies defined within the devDependencies from the package.json file that you see above. From now one the eslint-config package will be installing them.

Great, we have a new, global package with ESLint config that we can now share across the whole repository. So let’s proceed and install it for our Nuxt application. Inside the apps/web/package.json file add this notation to your devDependencies object.

"@yourmonorepo/eslint-config": "1.0.0",

You may also add workspace:* instead of the version number, but while publishing the package to the remote catalog you will get issues since this will be an internal (workspace) package.

Now, we need some small edits around the Nuxt’s app ESLint config.

As you can see almost everything remains the same, the only one difference is that now we’re importing the eslintBaseConfig from our global ESLint config package, finally extending it with our Nuxt-specific rules. Imagine that for every future app created inside our repository we will be able to do the same thing, never struggling with different ESLint rules. Perfect!

Two more things. Change this inside your main package.json file.

{
  "lint-staged": {
    "*.*": "turbo lint --"
  },
}

Because we’re defining locally per project which kind of files we went to scan it’s not needed anymore to determinate it along for the lint-staged proces. I stumble upon the issue of analyzing files as a tasks by Turborepo. To avoid this problem please add —- to your turbo lint command, this should resolve the issue.

That’s it! Now you can proceed with the other configs like Prettier or future-added Tailwind, or any other that you’ll be sharing across the repository.

What’s next? Docs, we need docs! Why? Check out the next post to learn more. And to not miss any please subscribe to this publication. Thanks and enjoy, Lukas.

Subscribe now

Please let me know how you find this article. What I can improve?

Before Start

I'm planning to write a series of articles on how to plan, design, and build applications with Vue & Nuxt - you may think about them as a comprehensive course or seminary. I'll be covering all the features, gradually breaking them down one by one - starting with the basics, showing how they work, and demonstrating how to use them effectively within the ecosystem. As we progress, I'll dive into advanced techniques and optimizations, equipping you with the knowledge to build highly efficient and powerful web applications.

Don't worry if something isn't covered right away - this journey is designed to build up your understanding step by step. Along with exploring specific parts of the framework, I'll also explain why they were built, what problems they solve, and how they fit into the bigger picture. By the end, you'll have a solid grasp of Vue & Nuxt, from the fundamentals to the most advanced techniques.

My only one request to you is simple - if you spot anything incorrect, outdated, or unclear, please let me know. Software evolves constantly, and some parts of this publication might become misleading over time. So don’t hesitate - reach out to me right away. I truly appreciate your feedback in keeping this content accurate and valuable. Thanks in advance, Lukas! 🚀

Last but not least - my take on AI. No doubt, you can work and learn with any leading GPT. However, I believe that truly understanding the context, seeing how everything connects, and learning without feeling overwhelmed requires proper “protein guidance”. AI can be a powerful tool, but it might not always provide the clarity and structured learning path that an experienced mentor can. Still, I’m just a human. 😅

Additionally, here you can read the coding guide, for better understanding the way and standards of how we will be approaching various things here.

Let’s Start

Alright, let’s dive into the main topic.

Nuxt 4? Wait a minute - it’s not even released yet, and there isn’t an official release date anywhere… Right, that’s true. But since the new, highly anticipated version of this popular Vue framework (as repeatedly announced) won’t be a major breaking change, it’s fair to say it’s almost here - and we can start introducing it. Even using it.

However, to be completely honest, this article will focus primarily on the first steps of Nuxt 3, along with some of the additional capabilities you can expect in/from the next version. It’s also worth mentioning that if you already have built application in Nuxt 3 you can easily switch to the new version, couple simple edits would be required tho.

OK, but what are we waiting for? Couple of things actually. First of all there must be a new version of Nitro released. Some of you might ask, what da heck is Nitro?

⚠️ Disclaimer

I think it’s really important to understand how the technology works - not just its APIs, primitives1, and abstractions2, but also what’s under the hood. This makes it easier to see how certain things work and how to approach them if we ever need to dig a bit deeper. Or if AI will stuck somewhere… So, from time to time, I’ll try to do that: dive deeper to show you how everything fits together. I hope this will be helpful.

Nitro... Nitro is a server-dedicated toolchain/framework built for H3. 😜 Dude, c’mon, what’s H3 now?! Stick with me here - so if you know Express.js, you'll see that H3 is essentially a similar framework for building a web server architectures. The key difference? H3 is a minimal wrapper around the Node and Web APIs, along with dedicated adapters. It offers a simpler, more intuitive interface with dedicated helpers and/or macro functions3 to define instances, events, and routes. Plus, it's built with TypeScript, so you get that type safety and an awesome development experience. Although, as mentioned before H3 is a really small framework focused only on essentials. Now, Nitro provides additional abstraction to build these web servers with ease. It comes with predefined configurations, dedicated directory structure, planty of utilities and integrations.

And for those working with Nuxt? Nitro's here as well. It means that when you’re creating your server APIs within the Nuxt’s application structure you’re doing it using Nitro (with H3) as a backbone. OK, but this is just a context, to realize the current state better. And to align the position in which Nuxt currently is it’s really important to mention this PR that we’re waiting for. Accordingly, some (not much) but important things left to be delivered. And as Nitro’s an integral piece of the Nuxt’s architecture it must be well finished and released just before. The great message here is that it’s not stopping us, we can still play with upcoming Nuxt 4 APIs while still using some old internals. Finally, migrating to the newest version should be (as authors claimed) should be easy and straightforward.

While you're reading this, the code and product are free and open-source. The authors are working pro bono for the community, so if you’d like to speed things up and join the movement, you can always contribute and help close issues faster. Go!

Hope to write a quick update soon. ☺️

Installation

Here you will find the installation guide for the current Nuxt (3) version along with the instruction on how to enable the new one (4). It’s a matter of simple configuration, so let’s dive into it.

In your terminal use this command.

npx nuxi@latest init [project-name] 

To not copy this just like that, soulless, we could check what’s going on here - I believe for some of you it might be quite informative. Quick reminder here: I’ll be approaching stuff that way, helping you to understand more, as mentioned above.

OK, let’s back to the code. What we have here is a command to call npx - the Node Package Execute (runner). It’s included with npm that you’re using to manage and install packages within your Node applications. npx is able to execute packages without even having them installed before. So using it makes the flow much seamless, both for user to get, and for the packages authors to deliver them to end user. Yarn and PNPM will use dlx tool to do the same thing.

Now, npx is calling nuxi, the official Nuxt’s CLI4 tool able to setup, upgrade, extend or even clean your Nuxt project. Here, we’re (init)ializing a new one, inside a new folder that the name we will provide for it - replace [project-name] with your project name. You can also initialize the new project inside existing directory, to do so you need to use this command.

npx nuxi@latest init

Just after nuxi will ask you if it should overwrite the existing folder contents or maybe create a new one. Then you will be able to select what kind of package manager you’ll be using, accordingly to our code guidelines we’ll stick to the pnpm. However, you can always run it with your desired package manager.

💡 Interesting Fact

I'm always amazed by how vast the Nuxt ecosystem is. Take nuxi, for example - it's built on top of citty, an unjs CLI builder (unjs being a collection of Nuxt community-driven projects that provide agnostic libraries for building high-performance JavaScript applications).

This is just one of many examples of how interconnected and well-structured the Nuxt ecosystem is. Throughout this series, I'll systematically unpack these tools, showing you how various internal components come together to complement the entire Nuxt ecosystem and its extended family.

At the end CLI will ask you if you want to establish a new git project, you can decide on that and let the process to finish by installing all of the dependencies.

What you’ll get will be this structure.

Alright. If you've worked with Nuxt 2 before, you'll notice that the structure in Nuxt 3 is quite different—more minimalistic. Gone are the numerous folders with README files explaining what each one does.

The “new” (well, not so new anymore) Nuxt approach is all about progressive enhancement - your app grows organically as your development process unfolds. And that’s exactly how we’ll approach it here. This way, you won’t be overwhelmed by a complex, pre-defined structure or find yourself stuck wondering what to do next. Instead, you’ll build up your app step by step, naturally understanding how everything fits together.

Two things here. The rest I’ll describe in a minute.

1. .nuxt/ folder - auto-generated folder that has all of the Nuxt internals. Don’t remove this one, it’s important for your application to work properly.

2. app.vue component - your application entry point, the place where your code “begins”. Inside you’ll find some of the Nuxt Welcome Page “native", pre-added components.

OK, now is the perfect moment when we can make these significant few steps entering into the Nuxt 4 world.

1. In your nuxt.config.ts file add future.compatibilityVersion property and set it to 4 (number).

   

   Thanks to this “flag” your application will be able to use all the new features and opted-in enhancements coming straight from the Nuxt 4 version. The future object is meant to be a container for futures that become a default ones. There is one more similar object called experimental with which you can enable these new and potential features, it’s not set in stone tho that they will finally land within the stable major/minor release.

2. Introduce a new directory structure - a simple rotation. However, if the structure of your application’s more mature than this simple initial one you don’t need to make these changes at any cost. Nuxt will detect the old arrangement and will adopt to it, still delivering new features.

   

   OK, let me unpack this:

   • There is a new app directory, it’s now a new source one (srcDir), this means that everything outside of this folder is a part of the root (rootDir).

   • Folders like (if you have them) layers, modules or public will be now relatively resolved to the rootDir path.

   • Historically, Nuxt wasn’t designed for building full-fledged client/backend applications with APIs. The server/ folder was gradually introduced as the framework evolved to accommodate growing backend needs. However, as internal backend applications expanded, developers faced challenges managing the distinct client and server contexts. Now, with Nuxt 3, this new folder structure contributes to a more seamless and powerful development flow. And what’s exciting is that we’ll be diving into this as well - going far beyond traditional SPA development and exploring how Nuxt can be used to build full-stack applications.

   • server/ (backend API) folder has now fully autonomous context along with dedicated TS configuration that you can manage from its dedicated tsconfig.json file.

Now, the important note: Since we're starting a brand-new application, further changes may be introduced as we progress through development. However, if you're migrating from an older version (3) with an advanced and extensive project structure, I highly recommend following the official migration guide provided by the Nuxt team. There are some significant changes you’ll need to address to ensure your application runs smoothly and fully benefits from the new Nuxt 4 features.

Some of them, which worth put attention to:

• normalized components name,

• inline styles granularity,

• sharing prerendered data - this one is powerful new feature, very anticipated, introduced recently as an experimental feature, in nutshell it allows to use prefetched data across the different pages, one important thing here might be to use dedicated to data keys while retrieving it from the store (will introduce it later).

That’s it. The rest have (or should have) minimal impact on your codebase, should be as well resolved automatically along with the Nuxt’s internal logic.

Further Steps

Time to move on and start building some sexy stuff. 😜 Let’s dive into the next steps, which are crucial from an overall application development perspective. Some of these decisions might have a big impact down the line, so let's make them wisely!

Hey, but first fire your app dude! Run this command.

pnpm run dev

You should see something like this.

As you can see your app will be running as a Nuxt 3 one, however all the compatible features with version 4 will be enabled. That’s what we exactly want for the moment.

Web App Configuration

Now that we have a slightly different directory structure and our web app is separated from the server, we might need some dedicated configuration for the client side. Fortunately, Nuxt already provides this feature through the app.config.ts file. It’s important to understand that app.config.ts is not an extension or replacement for nuxt.config.ts. Instead, it is meant to be used at build time and should only contain public data - it does not have access to environment variables and should never store sensitive information. For managing environment-specific configurations securely, we use runtimeConfig inside nuxt.config.ts, which allows access to values that need to remain private or change at runtime.

OK, let’s add this file, although let’s leave it empty for now.

Two additional things - to keep in mind but don’t overthink them just yet. First, you can add types for both the input and output of the configuration by extending the AppConfigInput interface inside the index.d.ts file. Second, the app.config.ts file can be merged with other app.config.ts files within Nuxt layers - if you define them and use a special merging function. As we progress with development, we’ll explore these features in practice, extending and using them as needed.

Share vue.house

Finally, If you want to reach data from that app config you can use built-in composable called useAppConfig(). It will provide you an reactive object with predefined configuration. Call it whenever (any component) you need to get access to app configuration. Important addition may be that it’s available both for server, and client side.

const appConfig = useAppConfig()

Pages

Nuxt automatically generates routes based on the pages/ folder structure. While it still uses vue-router under the hood, Nuxt simplifies the process by eliminating the need to manually define route objects or extensive router configurations. However, if you want more control, you can define routes manually. To do this, create a router.options.ts file inside your app/ directory. Within this file, you can set custom rules for your routes, something like this.

It's also important to note that if you don’t provide a pages/ folder, Nuxt will not include vue-router by default. In this case, your application will rely on a single entry point: the app.vue component inside the app/ directory.

However, let’s assume you choose the default approach and create a pages/ folder. This way, Nuxt will automatically generate your routes, making navigation effortless while keeping your project structured and scalable. From that state you have two path that you can go with.

1. Leaving the app.vue component as an application entry point. With that you’ll need to use <NuxtPage/> component as an page content container. This way content of any new page will be located within this exact destination. Around this you can create your own dedicated layout, or build external dedicated one - about layouts I’ll write within the next posts.

   

   Back in the day, the app.vue component was the true entry point for a Nuxt/Vue application. It was where you initialized the app and had the option to extend it with external tools. Now, things work a bit differently - you can handle all of this through Nuxt configuration files instead. If you're using the pages/ directory for default, automatic routing, it makes sense not to rely on app.vue as your entry point. That said, if you're building a single-page app, a simple landing page, or a lightweight single-page setup, sticking with app.vue can still be a practical choice. If not go with option 2.

2. Removing app.vue and creating/using only the index.vue file inside your /pages directory. This way you’ll not need the <NuxtPage/> component anymore, and everything what you’ll put inside the pages/index.vue component will became your app entry point instead. Original contents from app.vue file move to index.vue one.

   
   Default layout will be applied automatically… bit more about this within the next posts. So if you don’t want to miss any of the upcoming materials please subscribe.

Subscribe now

Linter & Prettier

Nuxt has its own, dedicated module for ESLint5 integration. To not mess and overcomplicate things at the very beginning let’s use it. Further, we will be able to extend or change this setup. Although, handling it as a “native” solution might be beneficial for now.

Run with this command.

npx nuxi module add eslint

Nuxi will install all the ESLint internals for you. Packages @nuxt/eslint and eslint will be added. ESLint will be installed in new 9.x version ecquiped with the “new” flat configuration. Now, when you run your application again the eslint.config.mjs file should be created inside your root folder. If not (some issues may occur) you can still install it manually. Use this command.

pnpm add -D @nuxt/eslint eslint typescript

Then, add '@nuxt/eslint' to your modules array in nuxt.config.ts file. No matter if you’ll use the module or manual way you should install typescript package additionally - ESLint will need it anyway. At the end please add the eslint.config.mjs file to the root of your project. Like this.

Time for Prettier6. You can install it with this command.

pnpm add -D prettier eslint-config-prettier

Additionally, we will add a set of rules to complement ESLint. Prettier, along with the eslint-config-prettier package, will handle formatting and also cover all Vue-specific rules, so there’s no need to add anything extra. To see which rules are defined and how they work, you can check the source of the package.

Alright, now let’s create a configuration file for Prettier: prettier.config.mjs (let’s stay consistent with naming and formats). You’ll need something like this.

Most of Prettier’s defaults will be fine for most codebases, one thing that I would suggest is to extend your workspace line with from 90 to 120 characters, and to use single quotes along with any data structures. That’s it.

Let’s include prettier ESLint rules within its configuration. In the eslint.config.mjs file add this enhancement.

Finally, let’s add linting script to our package.json file. Like that.

By adding --fix you’re asking ESLint to fix all of your code bugs; if it’s possible of course. In most cases these will be a small corrects within your code syntax and style.

You can test it now. Run this command.

pnpm run lint

If everything’s as should be, you will get this error message.

Good! This means that the rules provided by eslint-config-prettier working as expected. However, from version 3.2 of Vue we don’t need to have a parent/root Node anymore, so this rule is not necessary here. To disable this warning you can add the vue/no-multiple-template-root rule to your eslint.config.mjs file. Like you can see it below, just after you can run lint command again.

Now, linter should not report any issues and problems with your code. Let’s go!

Husky

As a final step, to get things even more legit and more sexy we can add Husky. Husky is a git hook handler that is able to initialize certain process while running selected git actions. For instance, to parse our files with Linter and Prettier when we’ll be creating a new commit. With Husky we will also add lint-staged (repository) package thanks to which only staged files will be checked. Now, in your root run this command.

pnpm add -D husky lint-staged

You should be using Husky in version 9, as this configuration refers to it.

Just after inside your package.json file add this script.

Let’s run it to initialize Huksy’s internals.

pnpm run husky

Husky will create a dedicated .husky folder where all the necessary hooks will be added (as files). All of these files will be empty and ready to be filled-in with our desired commands. You can leave them along, or remove (except husky.sh), leaving just pre-commit one (this one will be in use) - up to you.

One additional note here: we defined husky script, not prepare one (as it’s common to do) because when pnpm will run the installation script it will always run the prepare script as well, so to avoid creating Husky files all over (overwriting edits) we’re using a different definition for the Husky init script.

Next, provide lint-staged proper configuration. Inside package.json file please add this notation.

As you can see this is the exact command as we have already defined for our lint script. So now we need to swap them, like that.

Great, now you can run lint-staged command.

pnpm run lint

You should see something like this.

Awesome, Lint Staged works as expected. Finally (I promise), we need to add the same command to our pre-commit git hook file. In the .husky folder, inside the pre-commit file provide this content.

You may want to comment the . "$(dirname "$0")/h" line as it may wrongly read your internal paths and exit the script without running the hooks. Please check the internals as it can be polyfied with your setup.

Now you can add file to git and commit them to the repository. Voilà!

Understand The Most Important Internals

To properly close this first chapter, and wrap version 4 first steps guide I’ll spin around some of the built-in Nuxt features to emphasize how they can help you with further development.

But first, if you’re not subscribed yet go and HIT that button!

Subscribe now

Auto Imports 🪝

Nuxt has this amazing feature of auto-imports that will help you write less code by automatically making certain composables, components, and utilities available without needing to import them manually - everything what you’ll put inside the components/, composables/ and utils/ folders. This keeps your code clean and reduces boilerplate.

So instead of:

import { useRoute } from 'vue-router';

const route = useRoute();

You just write:

const route = useRoute();

Managing Assets 🖼️

In Nuxt, the assets/ directory is used for static resources like styles, images, fonts, and other files that should be processed by Webpack or Vite. Unlike the public/ folder, files in assets/ are not directly accessible via a URL - they need to be referenced inside your Vue components or stylesheets. Nuxt also automatically processes styles placed inside assets/.

✅ Use assets/ for SCSS, images, and fonts that need processing.
✅ Use public/ for static files that should remain unchanged.
✅ Reference assets with @/assets/ or ~/assets/ in Vue and SCSS.
✅ Define global styles in assets/styles/ and load them via nuxt.config.ts.

State Management 🧵

In Nuxt, state management helps you store, update, and share data across components efficiently. While you can use Vuex (in Nuxt 2) or Pinia, Nuxt 3 (and now with Nuxt 4) introduces a simpler and built-in state management solution using useState().

Layers 🧱

Nuxt Layers are a powerful way to extend, reuse, and modularize Nuxt applications. They let you build applications with multiple codebases, making it easier to share configurations, UI components, and logic across different projects. Think of layers as Nuxt-powered micro-frameworks that can be stacked together like building blocks.

What’s next? Check out how to suit your newly created Nuxt 4 project within the monorepo. Turborepo to be more precise. Your app will be grateful, promise!

OK guys. That’s it for now. Please subscribe to this publication, this way you’ll not miss any further updates, and I’m planning to write a lot, very extensively. Thanks in advance for your trust and support, Lukas.

Subscribe now

Please let me know how you find this article. What I can improve?