Skip to content

Latest commit

 

History

History
235 lines (195 loc) · 7.82 KB

001-vetur-config-file.md

File metadata and controls

235 lines (195 loc) · 7.82 KB
  • Start Date: 2020-10-14
  • Target Major Version: 2.x & 3.x
  • Reference Issues: #2325, #2243, #1635, #815, #424
  • Implementation PR: (leave this empty)

Summery

A new configuration file for Vetur and VTI

Basic example

// vetur.config.js
/** @type {import('vti').VeturConfig} */
module.exports = {
  // **optional** default: `{}`
  // override vscode settings part
  // Notice: It only affects the settings used by Vetur.
  settings: {
    "vetur.useWorkspaceDependencies": true,
    "vetur.experimental.templateInterpolationService": true
  },
  // **optional** default: `[{ root: './' }]`
  // support monorepos
  projects: [
    './packages/repo2', // shorthand for only root.
    {
      // **required**
      // Where is your project?
      // It is relative to `vetur.config.js`.
      root: './packages/repo1',
      // **optional** default: `'package.json'`
      // Where is `package.json` in the project?
      // We use it to determine the version of vue.
      // It is relative to root property.
      package: './package.json',
      // **optional**
      // Where is TypeScript config file in the project?
      // It is relative to root property.
      tsconfig: './tsconfig.json',
      // **optional** default: `'./.vscode/vetur/snippets'`
      // Where is vetur custom snippets folders?
      snippetFolder: './.vscode/vetur/snippets'
      // **optional** default: `[]`
      // Register globally Vue component glob.
      // If you set it, you can get completion by that components.
      // It is relative to root property.
      // Notice: It won't actually do it. You need to use `require.context` or `Vue.component`
      globalComponents: [
        './src/components/**/*.vue'
      ]
    }
  ]
}

Motivation

  • The VTI need some method to set configuration.
  • The monorepo need a baseline or logic.
  • VSCode workspace config is own by vscode. I don't want to commit it in git.
  • Shared settings required for team projects.
  • Register global vue component.

Detailed design

Noun

  • Vetur: a VSCode extension for Vue support.
  • VTI: a CLI for Vue file type-check, diagnostics or some feature.
  • VLS: vue language server, The core of everything. It is base on language server protocol.

Config file spec

  • All path formats are used with /.

    Helpful for cross-platform use project.

  • Only support commonjs format.

    We can use it quickly and directly.

  • Use pure JavaScript.

    Same as above. You can get typings like @JSDoc.

  • UTF-8 charset

How to use

VTI

You can use it to override VTI default settings.

vti `action`
vti -c vetur.config.js `action`
vti --config vetur.config.js `action`

Vetur

This profile takes precedence over vscode setting. It will find it when Vetur initialization. If it isn't exist, It will use { settings: {}, projects: ['./'] }. This will ensure consistency with past behavior.

How to find vetur.config.js

  • Start from the root and work your way up until the file is found.
  • The root is set process.cwd() value in VTI and you can set file path in CLI params.

PS. Each root can have its own vetur.config.js in VSCode Multi root feature.

Property detail

Definition

type Glob = string

export interface VeturConfig {
  settings?: { [key: string]: boolean | string | Enum },
  projects?: Array<string | {
    root: string,
    package?: string,
    tsconfig?: string,
    snippetFolder?: string,
    globalComponents?: Array<Glob | { name: string, path: string }>
  }>
}

settings

Incoming to vue language server config.

In VLS, it will merge (vscode setting or VTL default config) and vetur.config.js settings.

import _ from 'lodash'

// original vscode config or VTI default config
const config: VLSFullConfig = params.initializationOptions?.config
  ? _.merge(getDefaultVLSConfig(), params.initializationOptions.config)
  : getDefaultVLSConfig();

// From vetur.config.js
const veturConfig = getVeturConfigInWorkspace()
// Merge vetur.config.js
Object.keys(veturConfig.setting).forEach((key) => {
  _.set(config, key, veturConfig.setting[key])
})

Notice: It only affects the settings used by Vetur. For example, we use typescript.preferences.quoteStyle in Vetur. so you can set it. But it don't affect original TypeScript support in VSCode.

projects

The monorepo need a baseline or logic. Possible options are package.json or tsconfig.js. But both are used for node and typescript projects. We're likely to waste unnecessary resources on things we don't need. So I figured the best way to do it was through the setup.

For detailed discussion, see this RFC.

if projects[] is only a string, It is a shorthand when you only need to define root.

projects[].root

All runtime dependencies is base on value of this property. Like typescript, prettier, @prettier/pug. Also Vetur find ./package.json and ./tsconfig.js by default.

projects[].package

We can get the project name or dependency info from here. But We only use it to determine the version of vue now. But it doesn't rule out the use of more.

projects[].tsconfig

Typescript project profile. It's the key to helping us support JavaScript and TypeScript. We also use it for support template interpolation.

Why isn't array?

If you are familiar with typescript, You know TypeScript allow support multiple discrete tsconfig. But in the vue ecosystem, It's almost completely unsupported. For example, We often use webpack to compile Vue projects. The vue-loader call ts-loader for support typescript. But ts-loader is only support only one tsconfig.json.

For these reasons, we also don't support it. It can reduce development and maintenance costs.

PS. jsconfig.json is also support it.

projects[].snippetFolder

Vetur Custom snippets folder path

projects[].globalComponents

We have some amazing features, Like template interpolation. But it only work when register component in component. For example:

import Comp from '@/components/Comp.vue'

export default {
  components: {
    Comp
  }
}

With this property available, we will parse vue component files that match the glob on vls startup. You can support template interpolation for that components anywhere in the project.

This property allow two type values in array.

  • Glob (string) format Vetur will call glob lib with projects[].root for loading component when value is string. It use path.basename(fileName, path.extname(fileName)) as component name.
  • Object ({ name: string, path: string }) Vetur use this data directly. It's the most flexible way. If this is a relative path, It is based on projects[].root.

Notice: It won't actually do it. You need to use require.context and Vue.component in your project. more

Drawbacks

  • We need to guide the user through the new settings.
  • Monorepo's support is not so automatic.
  • Maintenance required to read configuration file code
  • Working with multiple profiles may confuse users.

Alternatives

  • Use vscode configuration file.
  • Put configuration to vue.config.js.

    Additional communication with vue-cli maintainer is required.

  • Use more cli params in VTI.

Adoption strategy

No any breaking change on it.

To guide user, We can add a dialog when open project, Or open a help page when vetur extensions install, and add help in the document in Vetur.

Unresolved questions

  • How to achieve Monorepo support?

    Another RFC. #2377