Nuxt Stack

Guide

Nuxt Stack is composed of two parts:

  • nuxt-stack-cli » Suite of Nuxt CLI commands for linting, testing, formatting etc.
  • nuxt-stack-module » Nuxt module that installs and configures a collection of plugins

Though these packages can be installed separately, you will get the most out of Nuxt Stack by installing nuxt-stack which includes both.

For a detailed rationale as to why you might want to use Nuxt Stack see here.

To get a detailed overview of the features provided by Nuxt Stack see here.

Getting started

# Make a new directory
mkdir example && cd example

# Install dependencies
yarn add nuxt nuxt-stack

# Initialise a new project
yarn nuxt init

# Start the dev server
yarn dev

Running nuxt init will generate a template project with all the files and configuration you need to get up and running. Take some time to look each of these files and appreciate the minimal contents of the obligatory dotfiles.

When you're ready, open the URL printed in the terminal when you ran yarn dev and you should see a page that looks like this.

This is the default "fancy" template that gets generated when you run nuxt init without any options. To see what options are available to you, check out the init command docs.

TIP

For a completely stripped back project template you can run nuxt init --template basic

If you're a VSCode user you'll want to add the --vscode flag to generate jsconfig.json and .vscode/settings.json files for resolving Nuxt path aliases and formatting your code when you save it.

To validate that the baseline app gets 100/100 on Google Lighthouse, run yarn generate and deploy the dist directory to a static site hosting service like Netlify. You can simply drag and drop the generated dist directory into Netlify. Copy and paste the URL generated by Netlify into Google's web.dev or run the audit locally from Chrome dev tool to see the results for yourself.

TIP

When running a Google Lighthouse audit locally, it is recommended that you do so in an incognito window since some Chrome extensions can impact the audit results.

Existing projects

Though you can add nuxt-stack to an existing project, it is highly recommended that you initialise one of the project templates if possible. This is because nuxt init generates all the config files you need to lint, format and test your app. It also injects some useful scripts into package.json while configuring husky and lint-staged. In addition to this, you might have dependencies listed in your package.json that are already included with nuxt-stack and don't need to be installed.

With that said, follow these steps to integrate nuxt-stack into an existing project:

  1. Create a feature branch in your project repo to sandbox the integration changes.
  2. Move your project's package.json and nuxt.config.js along with any config and ignore files into a temporary directory. These should include:
    • Git: .gitignore
    • EditorConfig: .editorconfig
    • ESLint: .eslintrc.js, .eslintignore
    • Jest: jest.config.js
    • Prettier: .prettierrc.js, .prettierignore
    • Husky: .huskyrc.js
    • Lint Staged: .lintstagedrc.js
    • CommitLint: .commitlintrc.js
    • VSCode: jsconfig.json, .vscode/settings.json
  3. Delete node_modules and any lock files (yarn.lock for example)
  4. Run yarn add nuxt nuxt-stack from your repo root so a fresh package.json is created containing only a dependencies field with nuxt and nuxt-stack within it.
  5. Now run yarn nuxt init --template basic --src-dir <src> where <src> is the directory where your pages, components etc. are located. If your pages and components are located at the root of the repo, just pass the flag with no value afterwards eg. nuxt init --src-dir. If your pages, components etc. are in an "app" directory then pass --src-dir app.

NOTE

The default source directory that Nuxt Stack configures when running nuxt init is "src" not the root of your repo. This is because it's much easier to write globbing patterns to target source files when they're located in a folder. It also separates your Nuxt app source code from any api, docs, server or tests directories that might be located at the root of your repo.

If you omit the --src-dir flag then a default value of src will be used.

  1. You should now have dotfiles for CommitLint, EditorConfig, ESLint, Git and Prettier as well as a minimal nuxt.config.js containing just nuxt-stack in the modules array. If you look at package.json you will find some scripts and configuration for husky and lint-staged have also been injected.
  2. Your project now has the baseline configuration for Nuxt Stack—congratulations!

TIP

Grab a cup of tea. The next bit is going to be a little tedious.

  1. First things first—remove anything that you don't want to use. If you don't want to use CommitLint to lint your git commits, you can delete the .commitlintrc.js file and the commit-msg hook from the husky config in package.json.
  2. You should then review Nuxt Stack's ESLint and Prettier configs to see if they are compatible or agreeable with your own. These can be found in the packages directory of the Nuxt Stack repo. For example, you might prefer using single quotes over Prettier's default double quotes. These settings will be used to format and lint your code when you start making changes and committing it to version control. You can either adopt Nuxt Stack's defaults (recommended) and use the CLI to update all files for you, or modify the configs to your liking.
  3. Copy and paste parts of your original package.json that you moved to a temporary directory over to the one generated when installing nuxt and nuxt-stack. You should copy across all the meta fields like name, description, repository, issues, license etc. If you had any Prettier, ESLint or Jest related fields in your original package.json, you should consider omitting those in favour of using the configuration files created by Nuxt Stack. Your call though! Think carefully when copying over your scripts since Nuxt Stack provides a number of new commands that might simplify the ones you had previously. Head over to the commands docs to learn more.

TIP

Take some time to review Nuxt Stack's config files for ESLint, Prettier and Jest. They can all be found in the repository packages folder. If you've setup ESLint or Jest to work with Nuxt before, these should look familiar to you.

  1. Install your project dependencies that are not included with Nuxt Stack. You shouldn't need to install any dev dependencies for ESLint, Prettier, CommitLint, Husky, Lint Staged and Jest since nuxt-stack-cli already depends on these. To figure out what [dev]dependencies you should install, check out the dependencies page. If your dependency isn't listed there, you should install it.
  2. Finally, start copying over parts of your nuxt.config.js. However before you do, spend some time reading the module docs to understand what Nuxt Stack is doing and how you might be able to simplify your nuxt.config.js by using the stack options to define shared meta data like the name and description for your app. Chances are Nuxt Stack has already configured some of the things you might have done previously like integrating eslint-loader with Webpack.

TIP

Grab another tea, step outside, take a deep breath and smile. You made it.

Rationale →