Revamp the essential style guide and mark others as legacy#3370
Revamp the essential style guide and mark others as legacy#3370haoqunjiang wants to merge 9 commits intovuejs:mainfrom
Conversation
✅ Deploy Preview for vuejs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
haoqunjiang
requested review from
kiaking,
ota-meshi,
phanan,
serkodev and
ubugeeei
|
I'll definitely check it! And every team members should check also! |
|
And since these are important changes, they should ultimately be decided by @yyx990803 |
|
Shall we add a style guide link to our menu by this PR? |
|
I don't think so because the other parts of the style guide are still outdated. |
|
What about still leaving the legacy style guide unreachable and creating another page for the new one? So we can make it available right now. Then we can put a link on the legacy docs to let users from there also able to know what happened and be properly navigated. |
|
I think that depends on what we plan to do next: do we stop at this essential guide, or are we going to revise the remaining style guides within a reasonable timeframe? |
|
Do you think should we seperate the Essential into JavsScript and TypeScript part (in session / different page) ? like "Declare emitted events" // BAD
function submit() {
$emit('submit', { email: form.email })
}it will never happen |
|
Thanks for the PR on this @haoqunjiang! My concern around narrowing the style guide to specific contractual Vue features is that it loses some of the best practices and guidances to avoid anti-patterns. Perhaps I'm mistaken, but I've always been under the impression the style guides are more about a collection of best practices that the team has found to make their apps better as a whole. If the team feels "avoid single word components" is too high, I'd propose we move it to "strongly recommended" instead of just deleting them since these are still proven conventions for avoiding conflicts in the codebase. |
| - In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error. | ||
| ::: | ||
| ::: 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. |
There was a problem hiding this comment.
Why did the second reason get removed from the explanation?
There was a problem hiding this comment.
I think the rephrased explanation could preserve a bit more nuance without getting into the technical details.
Detailed prop definitions not only let the Vue runtime warn about potential issues, but also help the TypeScript language server, linters, and similar tooling.
|
|
||
| </div> | ||
|
|
||
| ## Avoid `v-if` with `v-for` {#avoid-v-if-with-v-for} |
There was a problem hiding this comment.
Why is this rule being removed? Isn't it still relevant from a rendering / performance perspective?
There was a problem hiding this comment.
Yeah, but the v-for and v-if rules are so mechanical that a linter can catch them easily. And the ESLint plugin documentation already has dedicated pages for them. Do we really need to repeat the guidance here?
On second thought, I can still see a case for keeping the "keyed v-for" rule here because of the more detailed explanation of object constancy. But I don't really think the avoid-v-if-with-v-for rule belong here. It doesn't seem any more important than the other essential ESLint rules.
| - The [`scoped` attribute](/api/sfc-css-features#scoped-css) is not the only option. CSS modules, native [CSS `@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope), and disciplined class-based conventions such as [BEM](http://getbem.com/) can all work. | ||
| - App-level and layout-level styles may be global when they are intentionally shared. | ||
|
|
||
| ## Use computed for derived state {#use-computed-for-derived-state} |
| 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. |
There was a problem hiding this comment.
What does it mean for it to be "human-facing Vue rules"?
There was a problem hiding this comment.
Rules that rely more on human judgment and review, as opposed to ones that can be easily enforced by tools.
In principle, they could be AI-facing too, but I don’t think the current agent harness can reliably follow this many rules yet, and I haven’t found a better term for that distinction.
Co-authored-by: Ben Hong <ben@bencodezen.io>
Moved. That said, I haven't reviewed the rest of the "strong recommended" rules, so it's still marked as "legacy" overall. |
Yeah I think we'll eventually need that kind of toggle across the documentation, but I feel it would take a substantive amount of work, so it’s out of scope for this style guide revamp PR. For this particular issue, I changed the code example to show |
5 participants
This PR updates the Style Guide in a deliberately narrow way instead of attempting a full rewrite.
The diff:
keyed v-forandv-ifwithv-forentries from the essential section and leaves those checks to toolingmulti-word-component-namesfrom the essential sectionThe essential rules in this draft are:
Taken together, these rules define the core boundaries of a Vue component: its contract, its communication model, its styling boundary, and its reactive semantics.
Why This Direction
I think the guide should stay small, stable, and principle-driven, and leave mechanical concerns to tooling.
In practice, that means:
This is also partly motivated by vuejs/eslint-plugin-vue#3060: the outdated guide is starting to create friction for tooling and keeps outdated rules in circulation.
It is also informed by the last large style guide revamp attempt in vuejs/v2.vuejs.org#2839, where the scope was broad enough that review became difficult to finish.