Nuxt 3 Boilerplate

A Nuxt 3 starter boilerplate with a lot of useful features.

Quick Start

• This project using npm as package manager
• Clone this project to your computer git clone https://github.com/yuzumi/nuxt3-boilerplate
• Install dependencies npm install
• Run npm run dev to start development server and open http://localhost:3000 in your browser

Available scripts

Setup

Make sure to install the dependencies:

npm install

DevTools

Enable devtools:

npm run devtools:enable

Disable devtools:

npm run devtools:disable

Lint & format

Manually check types:

npm run typecheck

Find ESLint errors:

npm run lint

Find ESLint errors and try to fix them:

npm run lint:fix

Development Server

Start the development server on http://localhost:3000

npm run dev

Production

Build the application for production:

npm run build

Locally preview production build:

npm run preview

Check out the deployment documentation for more information.

Docker

Create and start the development container:

make dev-up

Stop and remove the development container:

make dev-down

Create and start the production container:

make prod-up

Stop and remove the production container:

make prod-down

Features

• src directory
• ESLint
• Strict type-checking
• Husky & Lint-staged
• i18n
• VueUse
• Pinia
• Nuxt DevTools
• Vitest
• Layouts
  • Default
  • Empty
• Error page
• 404 page
• Global types
• Composables
  • useAsset

Setup notes

src directory

1. Set srcDir option in nuxt.config file.

   // nuxt.config.ts
   
   export default defineNuxtConfig({
     srcDir: 'src/',
   });

ESLint

1. Install needed devDependencies

   npm i -D eslint eslint-plugin-vue

   npm i -D typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser @nuxtjs/eslint-config-typescript

2. Generate config file

   npx eslint --init
   
   > How would you like to use ESLint? To check syntax and find problems
   > What type of modules does your project use? JavaScript modules (import/export)
   > Which framework does your project use? Vue.js
   > Does your project use TypeScript? Yes
   > Where does your code run? Node
   > What format do you want your config file to be in? JavaScript
   > Would you like to install them now? No

   // .eslintrc.cjs
   
   module.exports = {
     "env": {
         "es2021": true,
         "node": true
     },
     "extends": [
         "eslint:recommended",
         "plugin:vue/essential",
         "plugin:@typescript-eslint/recommended",
         "@nuxtjs/eslint-config-typescript" // Add here
     ],
     "parserOptions": {
         "ecmaVersion": 13,
         "parser": "@typescript-eslint/parser",
         "sourceType": "module"
     },
     "plugins": [
         "vue",
         "@typescript-eslint"
     ],
     "rules": {
     }
   };

3. Add task scripts

   "scripts": {
     "lint": "eslint --ext .ts,.js,.vue .",
     "lint:fix": "eslint --fix --ext .ts,.js,.vue ."
   },

4. Update your VS Code settings to look like this:

   {
     "eslint.format.enable": true,
     "editor.codeActionsOnSave": {
         "source.fixAll.eslint": true
     }
   }

Strict type-checking

1. Install needed devDependencies

   npm i -D vue-tsc typescript @types/node

2. Enable the typescript.typeCheck option in your nuxt.config file.

   export default defineNuxtConfig({
     typescript: {
       strict: true,
       typeCheck: true,
     },
   });

3. Optionally add task script to manually check your types with nuxi.

   {
     "scripts": {
       "typecheck": "npx nuxi typecheck",
     },
   }

Husky & Lint-staged

1. Install Husky

   npx husky-init && npm install

2. Install Lint-staged

   npm install --save-dev lint-staged

3. Inside .husky/pre-commit replace npm test with npx lint-staged.

   #!/usr/bin/env sh
   . "$(dirname -- "$0")/_/husky.sh"
   
   npx lint-staged

4. In the root directory of your project, create the file .lintstagedrc.json with the following contents:

   {
     "*.{js,jsx,vue,ts,tsx}": "npm run lint:fix"
   }

VueUse

1. Install VueUse

   npm i -D @vueuse/nuxt @vueuse/core

2. Add VueUse to nuxt.config file

   // nuxt.config.ts
   
   export default defineNuxtConfig({
     modules: [
       '@vueuse/nuxt',
     ],
   })

Pinia

1. Install Pinia

   npm i pinia @pinia/nuxt

2. Add Pinia to nuxt.config file

   // nuxt.config.ts
   
   export default defineNuxtConfig({
     imports: {
       // Auto-import pinia stores defined in `~/stores`
       dirs: ['stores']
     },
     modules: [
       '@pinia/nuxt',
     ],
     pinia: {
       autoImports: [
         'defineStore',
         'storeToRefs',
       ],
     },
   });

Nuxt DevTools

1. To enable devtools run:

   npm run devtools:enable

2. To disable devtools run:

   npm run devtools:disable

Vitest

1. Install the following dependencies:

   npm i -D vitest jsdom @vitejs/plugin-vue

   npm i -D @vue/test-utils @nuxt/test-utils

2. Create your Vitest configuration file (vitest.config.js):

   // vitest.config.js
   
   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   
   export default defineConfig({
     plugins: [vue()],
     test: {
       globals: true,
       environment: 'jsdom',
     },
   })

3. Add the following script to your project:

   {
     "scripts": {
       "test": "vitest"
     }
   }

4. Create your first test:

   // tests/components/HelloWorld.vue
   
   import { describe, it, expect } from 'vitest'
   import { mount } from '@vue/test-utils'
   
   import HelloWorld from '../../src/components/HelloWorld.vue';
   
   describe('HelloWorld', () => {
     it('renders correctly', () => {
       const wrapper = mount(HelloWorld)
       expect(wrapper.html()).contain('Hello, world!')
     })
   })

Global types

1. At the root of your project create a directory named types with an index.ts file.

2. Add your global types declaration like in the example below.

   // ~/types/index.ts
   
   export { };
   
   declare global {
     interface User {
       id: string;
       name: string;
       email: string;
     }
   }

Templates

Other templates you may be interested in:

• nuxt3-awesome-starter
• nuxt3-starter
• nuxt3-boilerplate
• nuxt3-eslint-starter

License

MIT @yuzumi