diff --git a/src/style-guide/index.md b/src/style-guide/index.md index 8f7b747f60..714d0c14ba 100644 --- a/src/style-guide/index.md +++ b/src/style-guide/index.md @@ -4,42 +4,46 @@ outline: deep # Style Guide {#style-guide} -::: warning Note -This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new). +::: warning Status +This section is under active revision. Priority A: Essential is currently the maintained section of the guide. Priority B, C, and D are retained as legacy reference content. ::: -This is the official style guide for Vue-specific code. If you use Vue in a project, it's a great reference to avoid errors, bikeshedding, and anti-patterns. However, we don't believe that any style guide is ideal for all teams or projects, so mindful deviations are encouraged based on past experience, the surrounding tech stack, and personal values. +This is the official style guide for Vue-specific code. It is meant to help teams make sound architectural, semantic, and maintainability decisions in modern Vue applications. However, no style guide is ideal for every team or project, so mindful deviations are still encouraged when they are deliberate and well understood. -For the most part, we also avoid suggestions about JavaScript or HTML in general. We don't mind whether you use semicolons or trailing commas. We don't mind whether your HTML uses single-quotes or double-quotes for attribute values. Some exceptions will exist however, where we've found that a particular pattern is helpful in the context of Vue. +This guide focuses on a small set of human-facing Vue rules. It is not intended to mirror every rule that lint tooling may enforce. Tools such as [eslint-plugin-vue](https://eslint.vuejs.org/), formatters, and other static analysis can still cover broader mechanical correctness and consistency checks. -Finally, we've split rules into four categories: +For the most part, we avoid suggestions about JavaScript or HTML in general. We will not set explicit guidelines around formatting decisions like semicolons, quote styles, etc. These are decisions that are personal to each team and we recommend setting your own conventions with tools like [Prettier](https://prettier.io/) or [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html). + +Our goal is to provide guidance around patterns that are important within the context of Vue. + +## How to use this guide {#how-to-use-this-guide} + +- Start with the [essential rules](./rules-essential). They are the primary maintained part of this guide and focus on component contracts, explicit data flow, component boundaries, and the Vue mental model. +- Treat Priority B, C, and D as legacy reference pages. They may still contain useful conventions, but they are not part of the current maintained scope. +- If your team uses [eslint-plugin-vue](https://eslint.vuejs.org/), expect tooling to enforce additional syntax, correctness, and consistency rules that are not all repeated here. ## Rule Categories {#rule-categories} -### Priority A: Essential (Error Prevention) {#priority-a-essential-error-prevention} +### Priority A: Essential (Maintained) {#priority-a-essential-error-prevention} -These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue. +These rules focus on component contracts, explicit data flow, component boundaries, and the Vue mental model. They are written to guide human decisions, not to duplicate every lint rule. - [See all priority A rules](./rules-essential) -### Priority B: Strongly Recommended {#priority-b-strongly-recommended} +### Priority B: Strongly Recommended (Legacy Reference) {#priority-b-strongly-recommended} -These rules have been found to improve readability and/or developer experience in most projects. Your code will still run if you violate them, but violations should be rare and well-justified. +This page is preserved for historical reference. Its recommendations may still be useful, but they are not part of the current maintained scope. - [See all priority B rules](./rules-strongly-recommended) -### Priority C: Recommended {#priority-c-recommended} - -Where multiple, equally good options exist, an arbitrary choice can be made to ensure consistency. In these rules, we describe each acceptable option and suggest a default choice. That means you can feel free to make a different choice in your own codebase, as long as you're consistent and have a good reason. Please do have a good reason though! By adapting to the community standard, you will: +### Priority C: Recommended (Legacy Reference) {#priority-c-recommended} -1. Train your brain to more easily parse most of the community code you encounter -2. Be able to copy and paste most community code examples without modification -3. Often find new hires are already accustomed to your preferred coding style, at least in regards to Vue +This page is also preserved as legacy reference content. It may help teams that want additional conventions, but it is not part of the current maintained scope. - [See all priority C rules](./rules-recommended) -### Priority D: Use with Caution {#priority-d-use-with-caution} +### Priority D: Use with Caution (Legacy Reference) {#priority-d-use-with-caution} -Some features of Vue exist to accommodate rare edge cases or smoother migrations from a legacy code base. When overused however, they can make your code more difficult to maintain or even become a source of bugs. These rules shine a light on potentially risky features, describing when and why they should be avoided. +This page remains available as historical guidance on risky patterns, but it is not part of the current maintained scope. - [See all priority D rules](./rules-use-with-caution) diff --git a/src/style-guide/rules-essential.md b/src/style-guide/rules-essential.md index 0872dc499e..0c59ca6229 100644 --- a/src/style-guide/rules-essential.md +++ b/src/style-guide/rules-essential.md @@ -1,51 +1,16 @@ # Priority A Rules: Essential {#priority-a-rules-essential} -::: warning Note -This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new). -::: - -These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue. - -## Use multi-word component names {#use-multi-word-component-names} - -User component names should always be multi-word, except for root `App` components. This [prevents conflicts](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) with existing and future HTML elements, since all HTML elements are a single word. - -
-

Bad

- -```vue-html - - - - - -``` - -
- -
-

Good

- -```vue-html - - - - - -``` - -
+These rules define the most important boundaries in Vue components: what a component exposes, how data flows through it, how its styles are contained, and how derived state is kept separate from side effects. Follow them by default to keep components easier to understand, maintain, and evolve. ## Use detailed prop definitions {#use-detailed-prop-definitions} -In committed code, prop definitions should always be as detailed as possible, specifying at least type(s). +In committed code, props should be treated as a key part of the component's contract and be defined in as much detail as possible. -::: details Detailed Explanation -Detailed [prop definitions](/guide/components/props#prop-validation) have two advantages: +::: details Why this matters +Detailed [prop definitions](/guide/components/props#prop-validation) make a component's API easier to understand, easier to use correctly, and easier to change safely. +::: -- They document the API of the component, so that it's easy to see how the component is meant to be used. -- In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error. - ::: +In TypeScript, a type-based `defineProps()` declaration can also be used when the prop contract is fully described by its types.
@@ -114,7 +79,6 @@ const props = defineProps({ ```js // Even better! - const props = defineProps({ status: { type: String, @@ -133,67 +97,67 @@ const props = defineProps({
-## Use keyed `v-for` {#use-keyed-v-for} +## Declare emitted events {#declare-emitted-events} + +Treat emitted events as part of a component's public contract, and declare them explicitly. + +::: details Why this matters +Explicit [event declarations](/guide/components/events) document how a component communicates outward and make parent-child interactions easier to follow. +::: + +In Options API, declare events with the [`emits`](/guide/components/events#declaring-emitted-events) option. In [` + + ``` - +```vue + -**Never use `v-if` on the same element as `v-for`.** + +``` -There are two common cases where this can be tempting: + -- To filter items in a list (e.g. `v-for="user in users" v-if="user.isActive"`). In these cases, replace `users` with a new computed property that returns your filtered list (e.g. `activeUsers`). + -- To avoid rendering a list if it should be hidden (e.g. `v-for="user in users" v-if="shouldShowUsers"`). In these cases, move the `v-if` to a container element (e.g. `ul`, `ol`). +## Keep parent-child data flow explicit {#keep-parent-child-data-flow-explicit} -::: details Detailed Explanation -When Vue processes directives, `v-if` has a higher priority than `v-for`, so that this template: +Pass data down with props, and communicate requested changes back up with emitted events. -```vue-html - -``` +::: details Why this matters +Vue components are easier to understand and maintain when state ownership is clear. Prop mutation and other implicit parent-child coupling make updates harder to reason about and components harder to reuse. +::: -Will throw an error, because the `v-if` directive will be evaluated first and the iteration variable `user` does not exist at this moment. +This includes `v-model`, which still follows the same prop-and-event communication pattern with shorthand syntax. -This could be fixed by iterating over a computed property instead, like this: +If a child needs editable local state, derive or initialize it from the prop instead of mutating the prop itself.
+
+

Bad

+ ```js -computed: { - activeUsers() { - return this.users.filter(user => user.isActive) +export default { + props: { + open: Boolean + }, + + methods: { + requestClose() { + this.open = false + } } } ```
-
+
+

Good

```js -const activeUsers = computed(() => { - return users.filter((user) => user.isActive) -}) -``` +export default { + props: { + open: Boolean + }, -
+ emits: ['update:open'], -```vue-html - + methods: { + requestClose() { + this.$emit('update:open', false) + } + } +} ``` -Alternatively, we can use a `