Creating type definitions (d.ts) for a vue JS component library

[guilherme-gm]

Hello,
I would like to create type definitions for a vue component library that is currently written in JS. I could not find a reference on how to properly do it nor any libraries that pop to mind that does it. Thus, I am looking for some guidance.

I tried creating a dummy component in a new vue app and getting its types, and with some digging into Vue source, I got to the following d.ts:

(Note: The component library I am using is installed as a plugin (app.use(library)) making every component globally available -- that's why I augmented vue's module too).

// CvButton.d.ts

import { DefineSetupFnComponent } from 'vue';

export type CvButton = DefineSetupFnComponent<
  // Props
  {
    disabled?: boolean;
    
  },
  // Events
  {
    click(event: MouseEvent): void;
  },
>;

declare module 'vue' {
  export interface GlobalComponents {
    CvButton: CvButton,
    'cv-button': CvButton,
  }
}

I found the DefineSetupFnComponent type in Vue source, so I am not sure whether it is really meant to be used this way...

From my tests this does work, I am just wondering if I am going the right path or this may be something that may break in a few months.

May you provide me guidance on whether I am going on the right path or if I am not, how should I do it?

Thank you in advance!

[s3xysteak]

If you are using Vite, it should be automatically resolved by vue-tsc and Vite. (lib mode)

// index.ts

export { default as MyButton } from './components/MyButton.vue'

(Note: The component library I am using is installed as a plugin (app.use(library)) making every component globally available -- that's why I augmented vue's module too).

Is that necessary to load components globally? I think unplugin-vue-components is a much more morden solution.

[guilherme-gm]

Ohhh that's interesting!! I didn't know vue-tsc and Vite could do that. We are not using vite in that project yet, but having the type generation automated is much better. I also didn't know about unplugin-vue-components.

Just to confirm I got it right:

1. The component library should use vue-tsc and Vite to get the types automatically generated from .vue/JS files (I would probably only need to create 1 ts file exporting them)
2. End users who are installing my library would need to use unplugin-vue-components to get the typings automatically loaded without my library augmenting vue.

Is that correct?

Thank you!

[s3xysteak]

Sorry I just saw this after a week. In detail, you can make your library by vite-plugin-dts(for types) and Vite:

pnpm create vue

In the project folder, make your components, and export it in a entry file like index.ts:

// If you have lots of components to export, maybe use a Nodejs script to generate the file

export { default as Button } from './Button.vue'
// ...

Install vite-plugin-dts:

pnpm i -D vite-plugin-dts

Create a file called tsconfig.build.json in the root:

{
  "extends": "./tsconfig.app.json",
}

tsconfig.app.json should be generated automatically when you use pnpm create vue.

In vite.config.ts:

// Basic config

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    vue(),
    dts({
      tsconfigPath: './tsconfig.build.json',
    })
  ],
  build: {
    lib: {
      entry:'./src/index.ts',
      formats: ['es'],
    },
    rollupOptions: {
      external: ['vue']
    }
  },
})

Configure it according to your needs.

Do not forget to edit your package.json:

{
  "exports": {
    ".": {
      "types": "./dist/src/index.d.ts",
      "import": "./dist/index.js"
    },
  },
  "module": "./dist/index.js",
  "types": "./dist/src/index.d.ts",
  "files": [
    "dist"
  ],
}

Which indicated what files will be used by users, also configure it according to your needs.

And that is how users use it:

<script setup>
import { Button } from 'my-library'
</script>

<template>
  <Button />
</template>

It is very troublesome to import it every time, so users can use unplugin-vue-components:

// users' vite.config.ts

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [
        {
          type: 'component',
          resolve: (name: string) => {
            if (name === 'Button')
              return { name, from: 'my-library' }
          },
        }
      ]
    })
  ]
})

Or you can also export the resolver in your library:

/** Maybe you wanna automatically generate it by Nodejs script*/
const LIST: Array<string> = []

export default function resolvers(): ComponentResolver {
  const set = new Set(LIST)

  return {
    type: 'component',
    resolve: (name: string) => {
      if (set.has(name))
        return { name, from: 'my-library' }
    },
  }
}

[guilherme-gm]

thank you very much for all the details, I have also been experimenting some things based on what you said in the previous message and getting interesting results 😄

[antarasi]

I was missing the

dts({
      tsconfigPath: './tsconfig.build.json',
    })

part, thank you!

[quoeamaster]

Hi, I have followed the above config; seems it did compiled a bunch of .d.ts files; however when I using a symbolic link approach for testing the component; somehow still the import would warn

Could not find a declaration file for module 'yourpackage'. '/path/yourpackage/dist/yourpackage.js' implicitly has an 'any' type.

and this is what I got after a success vite build

-rw-r--r--   1 user  staff   320 Apr 11 13:12 App.vue.d.ts
drwxr-xr-x   3 user  staff    96 Apr 11 13:12 components
-rw-r--r--   1 user  staff   183 Apr 11 13:12 index.d.ts
-rw-r--r--   1 user  staff     0 Apr 11 13:12 main.d.ts
-rw-r--r--   1 user  staff  1497 Apr 11 13:12 vite.svg
-rw-r--r--   1 user  staff  6887 Apr 11 13:12 vuetif-ts.css
-rw-r--r--   1 user  staff   639 Apr 11 13:12 vuetif.es.js
-rw-r--r--   1 user  staff   777 Apr 11 13:12 vuetif.umd.js

and index.d.ts has a definition details as follows

import { App } from 'vue';
declare const _default: {
    install(app: App): void;
};
export default _default;
export { default as SimpleButton } from './components/SimpleButton.vue';

so the issue is, you never know whether the build is correct (based on the above) OR it is something else mis-configured?

@s3xysteak would you have time to take a look?