When converting legacy Vue applications to TypeScript, third-party component libraries often become a stumbling block. Some popular ecosystem packages still lack first-party TypeScript definitions or ship incomplete @types packages, resulting in TS7016: Could not find a declaration file for module errors during build time.
In my recent contribution to GitLab's Contributors Platform (MR !3199), I converted the ProjectFilter component to strict TypeScript.
Here is how we handled untyped third-party dependencies with ambient declarations, implemented Vue 3.4's named defineModel macro, and tested scoped slot rendering.
1. Handling Untyped Libraries with Ambient Declarations (.d.ts)
The ProjectFilter component integrates the popular vue-select dropdown package to allow contributors to filter community issues across dozens of GitLab projects.
Because vue-select does not ship built-in type definitions, importing it in a TypeScript SFC produces compiler errors:
import VueSelect from 'vue-select'; // ❌ TS7016: Could not find declaration file
Instead of bypassing type checking with // @ts-ignore, the idiomatic TypeScript solution is creating an ambient module declaration in the project's source root (app/javascript/vue-select.d.ts):
declare module 'vue-select' {
import type { DefineComponent } from 'vue';
const component: DefineComponent<Record<string, unknown>>;
export default component;
}
Why this approach works:
-
Zero Suppression Comments: The compiler recognizes
vue-selectas a valid Vue component without polluting component files with suppressions. -
Global Availability:
vue-tscpicks up all*.d.tsfiles included intsconfig.json, enabling any other component across the codebase to importvue-selectsafely.
2. Implementing Named Two-Way Binding: defineModel('selectedProjects')
In Vue 3.4+, components can bind multiple models or use custom model names using the first argument of defineModel().
In ProjectFilter.vue:
<!-- After (TypeScript) -->
<script setup lang="ts">
import { BFormGroup } from 'bootstrap-vue-next';
import VueSelect from 'vue-select';
import 'vue-select/dist/vue-select.css';
defineProps<{
availableProjects: string[];
}>();
// Strongly typed named model with required flag
const selectedProjects = defineModel<string[]>('selectedProjects', {
required: true
});
</script>
<template>
<BFormGroup label="Project">
<VueSelect
v-model="selectedProjects"
multiple
:options="availableProjects"
>
<template #no-options="{ search, searching }">
<template v-if="searching">
No projects matching "{{ search }}"
</template>
<template v-else>
No projects available
</template>
</template>
</VueSelect>
</BFormGroup>
</template>
Improvements:
-
defineModel<string[]>('selectedProjects', { required: true })automatically types bothprops.selectedProjectsand emitsupdate:selectedProjectswith a payload ofstring[]. - Prop validation for
availableProjectsis enforced at compile time without verbose runtime type objects.
3. Testing Scoped Slots in Vue Test Utils
A unique testing pattern in ProjectFilter.spec.ts is verifying custom template slots like #no-options="{ search, searching }".
In TypeScript, accessing $slots on a child component's vm requires proper typing and optional chaining:
import type { VueWrapper } from '@vue/test-utils';
import { shallowMount } from '@vue/test-utils';
import VueSelect from 'vue-select';
import ProjectFilter from './ProjectFilter.vue';
describe('ProjectFilter', () => {
let wrapper: VueWrapper;
const findSelect = () => wrapper.findComponent(VueSelect);
// Type-safe slot helper rendering the child's scoped slot
const findNoOptions = (slotProps: Record<string, unknown>) =>
shallowMount({
render: () => findSelect().vm.$slots['no-options']?.(slotProps),
});
it('emits updated projects when selection changes', async () => {
createWrapper();
await findSelect().vm.$emit('update:modelValue', ['gitlab']);
// Emits are typed as Array of argument arrays
expect(wrapper.emitted('update:selectedProjects')).toEqual([[['gitlab']]]);
});
it('renders matching text when search has no results', () => {
createWrapper();
const noOptionsWrapper = findNoOptions({ search: 'non-existent', searching: true });
expect(noOptionsWrapper.text()).toContain('No projects matching "non-existent"');
});
});
Using optional chaining findSelect().vm.$slots['no-options']?.(slotProps) prevents runtime TypeError when a component's slot is undefined during mounting.
Key Takeaways
-
Ambient Declarations for Untyped Packages: Create clean
.d.tsdeclaration files instead of relying on@ts-ignorewhen working with untyped npm packages. -
Named
defineModel<T>('name'): Leverages Vue 3.4's macro to type non-default model bindings cleanly and succinctly. - Safe Scoped Slot Testing: Use typed inline render helpers with optional chaining to mount and assert custom slot templates in Vue Test Utils.
Check out the merged Merge Request on GitLab:
👉 GitLab Contributors MR !3199
Author: Manish Kumar
GitLab: @manishpatel00

Top comments (0)