Documentation request: Config recipes for minimal config setup

Question

Documentation request: Config recipes for minimal config setup

TribeWeb opened this issue 6 months ago · 5 comments

Describe the feature

I appreciate the work to consolidate the use of eslint and prettier with Nuxt. I am self taught and although I understand the general principles of what each of these packages achieves, I have limited understanding of how they are configured and have got this far without having to dive into them. I have always been able to copy others' configs and have been happy with that. I don't have opinions about semicolons and tabs/spaces as long as it's neat.

I am currently starting a project with Nuxt 3 (and the new Nuxt module) and for the first time, although some aspects are working, I can't get my code looking nice at all. If I look at other repos for clues (e.g. NuxtHub), they all seem to use something different to what's in the docs. I can't tell if the 3 packages listed are mutually exclusive or do I need a bit of each?

Because the linting and prettifying ecosystem seems to change frequently and is optimised for flexibility, it seems there are lots of ways I could get the configuration wrong. For example:

What should the settings in VS Code look like? Might I be overriding things by mistake?
Should I have a .vscode folder and settings.json file in each project? What should be in them?
Do I need typescript installed as a dev dependency? Or anything else in addition to @nuxt/eslint & eslint?
I'd be happy not to use prettier if eslint can make things look nice but if I add stylistic: true nothing happens - should I disable prettier in VS Code or do I need to install something else to the project to make it work?

It would really help me to have a simple recipe or example using the latest module (or a link to a well maintained example).
I think it would need to help me achieve some sensible defaults:

Sorting out my indenting & quotes etc so that by the time I save a file, it looks presentable like code on the Nuxt docs
Making all files in a typical Nuxt app look nice including .md files in the content folder (both frontmatter & markdown)
How to get eslint to prettify the files OR how to set up prettier alongside

I think it would help to be able to see:

What packages are added to package.json
What to look out for in VS Code settings that might get in the way (is there a way of using a .vscode folder and settings.json file to "reset" VS Code-wide settings on a project basis?)
What should be in a typical eslint.config.mjs file

I hope that would be helpful to others too and I'd be more than happy to help in any way I could.

Thanks

Rich

Additional information

Would you be willing to help implement this feature?
Could this feature be implemented as a module?

Final checks

Read the contribution guide.
Check existing discussions and issues.

Answer 1 · 2024-07-02T14:43:30.000Z

Trying to answer some of these questions based on my understanding and what I read on the docs. You should be able to set it up the way you described if you follow the instructions from the docs and ensure you have similar config to the one I'm sharing below.

Make sure to check the Eslint Output console in vscode to ensure there are no errors and everything is working correctly.

Hope this helps 👍

I can't tell if the 3 packages listed are mutually exclusive or do I need a bit of each?

According to the FAQ page on the docs you only need the module aka @nuxt/eslint.

What to use?

For new projects, we highly recommend using the ESLint Module which provides a project-aware ESLint flat config generation and is more future-proof.

If you still use the legacy .eslintrc format, you can use the ESLint Config package to manually configure your ESLint settings. We recommend you to migrate to the flat config format if possible.

If you are maintaining your custom ESLint config and want a low-level setup, you can use the ESLint Plugin package directly to enable some Nuxt-specific rules in your config.

What should the settings in VS Code look like? Might I be overriding things by mistake?

Should I have a .vscode folder and settings.json file in each project? What should be in them?

Here's what my .vscode/settings.json looks like:

{
  "eslint.useFlatConfig": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always",
  },
}

I use this file to make sure I don't force these settings on other projects that might use the older config format or different version of the tools. It also ensures other folks working on the project get the same benefits from eslint and other dependencies.

Not sure you need to add anything specific to your global settings but just in case here's what I have:

{
  "eslint.debug": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "vue",
  ],
}

Do I need typescript installed as a dev dependency? Or anything else in addition to @nuxt/eslint & eslint?

You do not. It already is a dependency of whichever packages need it.

Check the Manual Setup section in the docs for more info (you'll see there they only ask you to install @nuxt/eslint and eslint).

I'd be happy not to use prettier if eslint can make things look nice but if I add stylistic: true nothing happens - should I disable prettier in VS Code or do I need to install something else to the project to make it work?

Did you check the playground dir in this repo? It has a complete example of a working project.

Again, just in case, here's what my config looks like:

import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt()
  .override('nuxt/stylistic', {
    rules: {
      '@stylistic/arrow-parens': ['error', 'always'],
    },
  })

Answer 2 · 2024-07-04T12:04:21.000Z

Thank you for such an in-depth reply @hacknug

Make sure to check the Eslint Output console in vscode to ensure there are no errors and everything is working correctly.

Turns out one of the problems I had/have is that the language server in VS Code crashes fairly regularly so restarting VS Code after each eslint config change seems like very good advice.

Here's what my .vscode/settings.json looks like:

Brilliant - thank you.

Not sure you need to add anything specific to your global settings but just in case here's what I have:

Again, that was very helpful. I found I had to go into VS Code global settings and delete a bunch of rules that have accumulated before the project level settings worked.

Do I need typescript installed as a dev dependency? Or anything else in addition to @nuxt/eslint & eslint?

You do not. It already is a dependency of whichever packages need it.

I removed it but then when I tried the ESLint Config Inspector in Nuxt DevTools, it wouldn't load and gave me the message to install typescript. After re-installing typescript, it worked again.

Did you check the playground dir in this repo? It has a complete example of a working project.

I had not noticed it, but when I looked, there were extra rules in nuxt.config.ts that caused new warnings (the component rule) and the eslint.config.mjs file was empty. Your example was much more helpful - thanks.

One last thing, since changing my config, I now get the following error message every time I run yarn nuxi dev:
ERROR [unhandledRejection] Cannot find package 'vite-plugin-eslint2' imported from /Users/richardstephenson/LocalProjects/power2/node_modules/@nuxt/eslint/dist/chunks/checker.mjs.
It doesn't prevent the site from launching but I've no idea what's caused it. I've tried deleting node-modules and reinstalling.

Answer 3 · 2024-07-04T14:37:31.000Z

I removed it but then when I tried the ESLint Config Inspector in Nuxt DevTools, it wouldn't load and gave me the message to install typescript. After re-installing typescript, it worked again.

I think this is something specific to your project because I don't have it listed on my package.json and the eslint config inspector works flawlessly.

One last thing, since changing my config, I now get the following error message every time I run yarn nuxi dev:
ERROR [unhandledRejection] Cannot find package 'vite-plugin-eslint2' imported from /Users/richardstephenson/LocalProjects/power2/node_modules/@nuxt/eslint/dist/chunks/checker.mjs.
It doesn't prevent the site from launching but I've no idea what's caused it. I've tried deleting node-modules and reinstalling.

Not sure what could be causing this issue but did you try running npx nuxi@latest upgrade --force to force your package manager to regen tis lockfile and install the latest in-range version of your deps?

I personally use pnpm and in my lockfile I only see vite-plugin-eslint2 listed under @nuxt/eslint:

  '@nuxt/eslint@0.3.13':
    resolution: {integrity: sha512-3NSD713MVLlHuwXDSqNOS1KUj0L+CP/3a1vwdOpdTJd8h3vdZaJAQ3XBtsvV33fvNDgZ5DEHSMc/+5/xDh3Xpw==}
    peerDependencies:
      eslint: ^8.57.0 || ^9.0.0
      eslint-webpack-plugin: ^4.1.0
      vite-plugin-eslint2: ^4.4.0
    peerDependenciesMeta:
      eslint-webpack-plugin:
        optional: true
      vite-plugin-eslint2:
        optional: true

Answer 4 · 2024-07-08T08:59:30.000Z

Thanks again @hacknug. I've had another good play with the settings and I think I've finally got it working as expected.

I removed it but then when I tried the ESLint Config Inspector in Nuxt DevTools, it wouldn't load and gave me the message to install typescript. After re-installing typescript, it worked again.

I think this is something specific to your project because I don't have it listed on my package.json and the eslint config inspector works flawlessly.

You were absolutely correct that typescript is not required. When I tried to reproduce the issue, I found that the ESLint Config Inspector in Nuxt DevTools only loaded properly when the following eslint settings were in nuxt.config.ts (I think I had previously set stylistic: true somewhere else)

eslint: {
    config: {
      stylistic: true
    }
}

One last thing, since changing my config, I now get the following error message every time I run yarn nuxi dev:
ERROR [unhandledRejection] Cannot find package 'vite-plugin-eslint2' imported from /Users/richardstephenson/LocalProjects/power2/node_modules/@nuxt/eslint/dist/chunks/checker.mjs.
It doesn't prevent the site from launching but I've no idea what's caused it. I've tried deleting node-modules and reinstalling.

Not sure what could be causing this issue but did you try running npx nuxi@latest upgrade --force to force your package manager to regen tis lockfile and install the latest in-range version of your deps?

My lockfile actually looked identical to yours but I tried npx nuxi@latest upgrade --force and also changed from yarn to pnpm (something I'd been meaning to do for a while). None of this had any effect until I changed my nuxt.config.ts settings again. I had previously copied the eslint settings from nuxt.config.ts on the playground repo you linked to. Commenting out the checker settings got rid of the error.

eslint: {
    config: {
      stylistic: true
    }
    // checker: {
    //   lintOnStart: true,
    //   fix: true,
    // },
},

Now that I have a fully working eslint config, I may still write my own recipe before I forget what I did. Would that be worth sharing with you on this thread?

Answer 5 · 2024-07-27T21:31:57.000Z

Thanks for your help and great answers @hacknug!

I didn't follow the questions a lot, but I assume most of them should be resolved. I am marking this as closed for now. If you have any more doubts to the docs, or find some weird behaviour - please create issues/discussions for each of them so we could better keeping those conversations on track.

Thanks!