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.
# 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
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.
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
.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.
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.
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
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:
- Create a feature branch in your project repo to sandbox the integration changes.
- Move your project's
nuxt.config.jsalong with any config and ignore files into a temporary directory. These should include:
- Lint Staged:
node_modulesand any lock files (
yarn add nuxt nuxt-stackfrom your repo root so a fresh
package.jsonis created containing only a
- 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
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.
- You should now have dotfiles for CommitLint, EditorConfig, ESLint, Git and Prettier as well as a minimal
modulesarray. If you look at
package.jsonyou will find some
scriptsand configuration for
lint-stagedhave also been injected.
- Your project now has the baseline configuration for Nuxt Stack—congratulations!
Grab a cup of tea. The next bit is going to be a little tedious.
- 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.jsfile and the
commit-msghook from the
- 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
packagesdirectory 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.
- Copy and paste parts of your original
package.jsonthat you moved to a temporary directory over to the one generated when installing
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
scriptssince 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.
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.
- 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-clialready 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.
- 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.jsby using the
stackoptions to define shared meta data like the
descriptionfor your app. Chances are Nuxt Stack has already configured some of the things you might have done previously like integrating
Grab another tea, step outside, take a deep breath and smile. You made it.