Priority A Rules: Essential
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 Kdu.
Use multi-word component names
User component names should always be multi-word, except for root App components. This prevents conflicts with existing and future HTML elements, since all HTML elements are a single word.
Bad
<!-- in pre-compiled templates -->
<Item />
<!-- in in-DOM templates -->
<item></item>
Good
<!-- in pre-compiled templates -->
<TodoItem />
<!-- in in-DOM templates -->
<todo-item></todo-item>
Use detailed prop definitions
In committed code, prop definitions should always be as detailed as possible, specifying at least type(s).
Detailed Explanation
Detailed prop definitions have two advantages:
- They document the API of the component, so that it's easy to see how the component is meant to be used.
- In development, Kdu will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error.
Bad
// This is only OK when prototyping
props: ['status']
Good
props: {
status: String
}
// Even better!
props: {
status: {
type: String,
required: true,
validator: value => {
return [
'syncing',
'synced',
'version-conflict',
'error'
].includes(value)
}
}
}
Use keyed k-for
key with k-for is always required on components, in order to maintain internal component state down the subtree. Even for elements though, it's a good practice to maintain predictable behavior, such as object constancy in animations.
Detailed Explanation
Let's say you have a list of todos:
data() {
return {
todos: [
{
id: 1,
text: 'Learn to use k-for'
},
{
id: 2,
text: 'Learn to use key'
}
]
}
}
Then you sort them alphabetically. When updating the DOM, Kdu will optimize rendering to perform the cheapest DOM mutations possible. That might mean deleting the first todo element, then adding it again at the end of the list.
The problem is, there are cases where it's important not to delete elements that will remain in the DOM. For example, you may want to use <transition-group> to animate list sorting, or maintain focus if the rendered element is an <input>. In these cases, adding a unique key for each item (e.g. :key="todo.id") will tell Kdu how to behave more predictably.
In our experience, it's better to always add a unique key, so that you and your team simply never have to worry about these edge cases. Then in the rare, performance-critical scenarios where object constancy isn't necessary, you can make a conscious exception.
Bad
<ul>
<li k-for="todo in todos">
{{ todo.text }}
</li>
</ul>
Good
<ul>
<li
k-for="todo in todos"
:key="todo.id"
>
{{ todo.text }}
</li>
</ul>
Avoid k-if with k-for
Never use k-if on the same element as k-for.
There are two common cases where this can be tempting:
To filter items in a list (e.g.
k-for="user in users" k-if="user.isActive"). In these cases, replaceuserswith a new computed property that returns your filtered list (e.g.activeUsers).To avoid rendering a list if it should be hidden (e.g.
k-for="user in users" k-if="shouldShowUsers"). In these cases, move thek-ifto a container element (e.g.ul,ol).
Detailed Explanation
When Kdu processes directives, k-if has a higher priority than k-for, so that this template:
<ul>
<li
k-for="user in users"
k-if="user.isActive"
:key="user.id"
>
{{ user.name }}
</li>
</ul>
Will throw an error, because the k-if directive will be evaluated first and the iteration variable user does not exist at this moment.
This could be fixed by iterating over a computed property instead, like this:
computed: {
activeUsers() {
return this.users.filter(user => user.isActive)
}
}
<ul>
<li
k-for="user in activeUsers"
:key="user.id"
>
{{ user.name }}
</li>
</ul>
Alternatively, we can use a <template> tag with k-for to wrap the <li> element:
<ul>
<template k-for="user in users" :key="user.id">
<li k-if="user.isActive">
{{ user.name }}
</li>
</template>
</ul>
Bad
<ul>
<li
k-for="user in users"
k-if="user.isActive"
:key="user.id"
>
{{ user.name }}
</li>
</ul>
Good
<ul>
<li
k-for="user in activeUsers"
:key="user.id"
>
{{ user.name }}
</li>
</ul>
<ul>
<template k-for="user in users" :key="user.id">
<li k-if="user.isActive">
{{ user.name }}
</li>
</template>
</ul>
Use component-scoped styling
For applications, styles in a top-level App component and in layout components may be global, but all other components should always be scoped.
This is only relevant for Single-File Components. It does not require that the scoped attribute be used. Scoping could be through CSS modules, a class-based strategy such as BEM, or another library/convention.
Component libraries, however, should prefer a class-based strategy instead of using the scoped attribute.
This makes overriding internal styles easier, with human-readable class names that don't have too high specificity, but are still very unlikely to result in a conflict.
Detailed Explanation
If you are developing a large project, working with other developers, or sometimes include 3rd-party HTML/CSS (e.g. from Auth0), consistent scoping will ensure that your styles only apply to the components they are meant for.
Beyond the scoped attribute, using unique class names can help ensure that 3rd-party CSS does not apply to your own HTML. For example, many projects use the button, btn, or icon class names, so even if not using a strategy such as BEM, adding an app-specific and/or component-specific prefix (e.g. ButtonClose-icon) can provide some protection.
Bad
<template>
<button class="btn btn-close">×</button>
</template>
<style>
.btn-close {
background-color: red;
}
</style>
Good
<template>
<button class="button button-close">×</button>
</template>
<!-- Using the `scoped` attribute -->
<style scoped>
.button {
border: none;
border-radius: 2px;
}
.button-close {
background-color: red;
}
</style>
<template>
<button :class="[$style.button, $style.buttonClose]">×</button>
</template>
<!-- Using CSS modules -->
<style module>
.button {
border: none;
border-radius: 2px;
}
.buttonClose {
background-color: red;
}
</style>
<template>
<button class="c-Button c-Button--close">×</button>
</template>
<!-- Using the BEM convention -->
<style>
.c-Button {
border: none;
border-radius: 2px;
}
.c-Button--close {
background-color: red;
}
</style>
Avoid exposing private functions in mixins
Always use the $_ prefix for custom private properties in a plugin, mixin, etc that should not be considered public API. Then to avoid conflicts with code by other authors, also include a named scope (e.g. $_yourPluginName_).
Detailed Explanation
Kdu uses the _ prefix to define its own private properties, so using the same prefix (e.g. _update) risks overwriting an instance property. Even if you check and Kdu is not currently using a particular property name, there is no guarantee a conflict won't arise in a later version.
As for the $ prefix, its purpose within the Kdu ecosystem is special instance properties that are exposed to the user, so using it for private properties would not be appropriate.
Instead, we recommend combining the two prefixes into $_, as a convention for user-defined private properties that guarantee no conflicts with Kdu.
Bad
const myGreatMixin = {
// ...
methods: {
update() {
// ...
}
}
}
const myGreatMixin = {
// ...
methods: {
_update() {
// ...
}
}
}
const myGreatMixin = {
// ...
methods: {
$update() {
// ...
}
}
}
const myGreatMixin = {
// ...
methods: {
$_update() {
// ...
}
}
}
Good
const myGreatMixin = {
// ...
methods: {
$_myGreatMixin_update() {
// ...
}
}
}
// Even better!
const myGreatMixin = {
// ...
methods: {
publicMethod() {
// ...
myPrivateFunction()
}
}
}
function myPrivateFunction() {
// ...
}
export default myGreatMixin