Challenges with TS ESLint Type Aware Linting in Vue

[NonSpicyBurrito]

I have recently been working on some Vue projects and faced some challenges with using TS ESLint type aware linting in Vue. These challenges aren't new, as many of them already have existing open issues. I'm not familiar with the inner working of Vue, ESLint, TS ESLint, to offer any technical insight. Instead, the purpose of this post is to document these challenges, from the perspective of the developer with real world use cases, so hopefully it can raise some awareness about them and serve as a resource to the team.

What is Type Aware Linting

Type aware linting (or typed linting, linting with type information) is a feature of typescript-eslint where it leverages type information from TS to statically analyze your code.

An example could be:

if (auth.isExpired) {
    auth.refreshToken()
    alert('Token refreshed')
}

In this code, auth.refreshToken() is asynchronous and returns a promise, which is not awaited and thus the code has the problem of alerting user about successful token refresh without confirming that it indeed succeeded. @typescript-eslint/no-floating-promises can leverage the type information provided by TS that auth.refreshToken() indeed returns a promise, to warn you about the issue (or alternatively to know that auth.refreshToken() does not return a promise and thus the code is fine).

Type aware linting is a huge part of what makes TS ESLint powerful and is adopted by many.

Vue specific TS features

Vue has specific TS features, and to support these features the tooling ecosystem needs its Vue flavored counterparts like vue-tsc and language server. TS ESLint currently does not support these.

*.vue types

When Vue components are used as values, for example:

<script setup lang="ts">
import { type Component } from 'vue'
import CopyIcon from './icons/CopyIcon.vue'
import PasteIcon from './icons/PasteIcon.vue'

const tools: {
    title: string
    icon: Component
}[] = [
    {
        title: 'Copy',
        icon: CopyIcon,
    },
    {
        title: 'Paste',
        icon: PasteIcon,
    },
]
</script>

<template>
    <div v-for="{ title, icon } in tools">
        <span>{{ title }}</span>
        <component :is="icon" />
    </div>
</template>

TS ESLint cannot see the types of *.vue files, and thus the code triggers @typescript-eslint/no-unsafe-assignment: "Unsafe assignment of an error typed value."

One workaround to this problem is to simply disable the rule, which is what @vue/eslint-config-typescript currently does, however disabling the rule is not ideal as it won't be able to catch the problems it's intended for.

The better workaround is imo using a shim:

declare module '*.vue' {
    import { Component } from 'vue'

    const component: Component

    export default component
}

This shim serves no purpose for type checking with vue-tsc as vue-tsc already has the ability to resolve *.vue types, it's merely there to let TS ESLint have a fallback type so to not trigger false positives.

The workaround however may not work in certain cases, for example:

const result = await showModal(ConfirmCancelModal, {
    title: 'Cofirmation',
    message: 'Are you sure?',
})

In this case, showModal(modal, props) is a generic function over the modal argument, and the types of props and return value are derived from the modal component's props and emits. Depending on how the types are written, the above shim will result in TS ESLint seeing an undesirable type for result and triggering false positives again.

Instead, a "better" shim may be used:

declare module '*.vue' {
    const component: never

    export default component
}

With this shim, showModal can then be modified to handle never gracefully (perhaps it already works without further modification) so that when never is encountered the return value is also never. This then allows usage site to be modified into:

- const result = await showModal(ConfirmCancelModal, {
+ const result: boolean = await showModal(ConfirmCancelModal, {
    title: 'Cofirmation',
    message: 'Are you sure?',
})

During type checking, vue-tsc will make sure that the assignment is legal, and TS ESLint will be able to see result as boolean for rest of the analysis, preventing further false positives. While this is not ideal as you now have to explicitly type annotate the return type, it is however the best solution that does not compromise type checking or linting.

While the above workarounds solve the problem of component types, it does not solve the problem for module exports, for example:

<script lang="ts">
export type MyCompProps = {
    foo: string
    bar: number
}
</script>

<script setup lang="ts">
defineProps<MyCompProps>()
</script>

<template>
    ...
</template>

Similarly, TS ESLint cannot see type information from *.vue and report false positives:

import { MyCompProps } from './MyComp.vue'

const props: MyCompProps = {
    foo: '',
    bar: 42,
}

// Unsafe member access .foo on an `error` typed value. eslint(@typescript-eslint/no-unsafe-member-access)
console.log(props.foo)

Unlike the previous problem, this however has no satisfactory workaround. The best you can do is to put module exports into a separate file, effectively rendering using Vue SFC as modules unusable.

useTemplateRef

The type of useTemplateRef is enhanced to be a specific type depending on how it's used in template. This information is also invisible to TS ESLint:

<script setup lang="ts">
const container = useTemplateRef('container')

watch(container, (el) => {
    if (!el) return

    // Unsafe call of a(n) `error` type typed value. eslint(@typescript-eslint/no-unsafe-call)
    console.log(el.getBoundingClientRect())
})
</script>

<template>
    <div ref="container" />
</template>

This can be worked around by using a similar technique as previously:

- const container = useTemplateRef('container')
+ const container: Ref<HTMLDivElement | null> = useTemplateRef('container')

Similarly, this is a workaround that does not compromise type checking or linting, but less than ideal.

Linting in Template

Vue SFC templates simply do not get linted by TS ESLint, not just type aware linting. In an ideal world, templates should be simply the markup and contains no logic, and thus linting templates with TS ESLint may not be as useful, but that's rarely the case in real world code bases with logic sprinkled in template. Additionally, some type aware linting rules provide values even for markup.

Logic in Template

Logics in template do not get linted, including event handlers, props, text interpolations. Even for non complex code, there can be issues worth linting for, for example:

<div>
    {{ formatText(`${user.name}: ${user.profile}`) }}
</div>

In this case, @typescript-eslint/restrict-template-expressions may be configured to disallow user.profile to be interpolated due to it being an object and would result in undesirable [object Object].

Switch Exhaustiveness Check

Discriminated union is a widely used construct in TS, and @typescript-eslint/switch-exhaustiveness-check is one of the best rules to help with it. For example:

type User = Buyer | Seller

function doSomething(user: User) {
    switch (user.type) {
        case 'buyer':
            // ...
            break
        case 'seller':
            // ...
            break
    }
}

Upon refactoring to add a new Admin variant, the rule will detect that the switch does not exhaustively handle all variants, which is a huge help in refactoring a large code base.

Due to the lack of type aware linting for template as well as a lack of an equivalent construct, such a rule does not exist to help refactoring similar template code:

<div v-if="user.type === 'buyer'">
    ...
</div>
<div v-else-if="user.type === 'seller'">
    ...
</div>

A workaround is to move each code into its own component, and rely on type checking rather than linting:

<script setup lang="ts">
import BuyerDisplay from './BuyerDisplay.vue'
import BuyerSeller from './SellerDisplay.vue'

const userDisplays = {
    buyer: BuyerDisplay,
    seller: SellerDisplay,
}
</script>

<template>
    <component :is="userDisplays[user.type]" :user />
</template>

When a new variant is added, a type error will be triggered on userDisplays[user.type]. While this works, it is not ideal as now handling of each variant must now be its own component.

Conclusion

The post documents some challenges when using TS ESLint type aware linting in Vue with real world use cases.