All about the nuxt.config.ts file

The nuxt.config.ts is the heart and soul of your Nuxt app. With a few key/value pairs you can completely configure your Nuxt app to tailor it 100% to your needs. For example, you could:

• Switch between server-side rendering and client-side rendering
• Include assets that can be transformed at build time
• Configure the bundler (Vite / Webpack) to fine-tune control
• Configure the Nitro server running the Nuxt backend
• Include and configure Nuxt Modules
• Define your site-wide SEO / Head options
• Configure route-based rendering modes
• and a whole lot more

In this post we're going to look at some of the configuration options, so you know what you have at your disposal.

Defining a configuration

Nuxt has a great Auto Imported Function that helps you define your config called defineNuxtConfig. By using a function like this (instead of just exporting an object) you get suggestions and autocompletions while you configure your app. A base config would look something like this:

export default defineNuxtConfig({})

Remember you don't need to import this function into the file, if you get issues you might need to install the Volar plugin or you just need to run npx nuxi prepare as we discussed in the Nuxi Deep Dive.

Bundling CSS into your application

Vue allows us to inline <style></style> into our components, but sometimes we just want global CSS to be bundled right into our application. To do this simply create a assets/styles.css file within the project root:

body {
  font-family: comic, sans-serif;
}

Then we can tell Nuxt to bundle this into our application with the css property of the Nuxt Config:

export default defineNuxtConfig({
  css: ['~/assets/styles.css']
})

If we look at the source of our Nuxt app in the browser, we'll be able to find this CSS bundled into the application. The true power of this is if we for example include CSS that needs to be transformed. Currently TailwindCSS is a pretty popular CSS paradigm. It requires some tools to transform and tree shake your page's CSS though. So in the Nuxt config we could specify that:

export default defineNuxtConfig({
  css: ['~/assets/styles.css', '~/assets/tailwind-base.css'],
  postcss: {
    autoprefixer: {},
    tailwindcss: {},
  }
})

And voila, we have it all. Note that these packages need to be installed separately, but the key here is that the Nuxt config understands the postcss property.

Configuring SEO in the nuxt.config.ts

If you have an app that just needs some basic SEO base configuration you can always access the head of your html page:

export default defineNuxtConfig({
  app: {
    head: {
      title: '',
      script: [],
      meta: [],
      link: [],
    }
  }
})

Using Nuxt as a SPA / single page application builder

To switch from the powerful SSR / ISR modes you can easily tell Nuxt to render for the client only:

export default defineNuxtConfig({
  ssr: false,
})

How to treat your nuxt.config.ts

Instead of me going through every single property that is available within the Nuxt Config (which is available here), I will offer some advice. Treat the Nuxt Config on a 'need-to-use' basis only. The default configuration is fine and your app will work. But occassionally you'll need to add a module, or you'll want to bundle your CSS. Then before trying to figure out what code you need to write to do this, go through the Nuxt Config reference and see if there isn't a way to tell Nuxt to do it for you via the config file.

In the upcoming sections we'll be looking at rendering modes and route-based rendering modes, these are the perfect example of where the Nuxt Config becomes powerful. If you are limited to hosting static files on a hosting provider, you'll need to configure Nuxt to do so. If you have areas of your app that you want to pre-render or cache, and some can be rendered on the fly - the config file can help.

Config before hacking

So the key take away here is that the nuxt.config.ts file is powerful and most of the time when you're looking to acheive something that Nuxt doesn't do in its base configuration, this is where you'll look to acheive it.