Web-types – Filling a Vue Libraries Documentation Gap
As a Java and TypeScript developer, I’m so accustomed to having precise information for library symbols in the editor while coding that I never visit any online documentation. Yet, when developing a Vue application, I often had to switch back and forth between my editor and the online library documentation. I wasted a lot of time tracking down information, which was simply frustrating.
Since we develop in TypeScript and provide IDE support for it as well, we know how useful type definition files (
What is web-types?
Web-types is an open source standard for documenting various web frameworks. In its first iteration, it’s focused only on Vue support. The documentation consists of a single JSON file. The good news is that it’s already supported by some major Vue libraries – you can get detailed documentation for bootstrap-vue, quasar, vuetify, nuxt.js, and @ionic/vue while coding in WebStorm.
Private Vue libraries of many companies are also shipped with web-types. Good in-place documentation – code completion, validation, and quick documentation – significantly improves the onboarding process for developers and allows them to quickly learn about new components and their features.
Last but not least, web-types can be used for documenting your own project. This can come in handy when, for example, you register your components in a very specific way that can prevent an IDE from recognizing them. It can also help whenever you want to document your directives or provide detailed information about component events and slots.
How to build web-types?
Building a web-types JSON is relatively easy. A JSON Schema is available here, so you have autocompletion and documentation directly in your editor if the file is named
web-types.json. Usually, though, you’ll want to generate the file from your Vue library source code. You can develop your own build script to extract information. If you use JSDoc-style documentation for components, you can use the vue-docgen-web-types package to generate the file.
We’re dedicated to promoting the web-types standard, so you can expect many more libraries and frameworks, like Web Components, to support detailed documentation in the future. However, we won’t be able to achieve much without support from the community. We’re counting on you to contribute web-types to your favorite Vue libraries. Links to similar PRs can be found here.
The WebStorm team