{"id":108219,"date":"2021-01-19T13:21:54","date_gmt":"2021-01-19T12:21:54","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=webstorm&p=108219"},"modified":"2021-08-13T09:33:58","modified_gmt":"2021-08-13T08:33:58","slug":"web-types","status":"publish","type":"webstorm","link":"https:\/\/blog.jetbrains.com\/zh-hans\/webstorm\/2021\/01\/web-types","title":{"rendered":"Web-types \u2013 Filling a Vue Libraries Documentation Gap"},"content":{"rendered":"

As a Java and TypeScript developer, I\u2019m 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.<\/p>\n

What if we could provide developers with all of the needed information about Vue libraries in the editor as well? That\u2019s the question we asked ourselves in the WebStorm team some time ago. Back then, our Vue support was based on analyzing JavaScript files shipped with Vue libraries. This approach was delivering incomplete results and it wasn\u2019t possible to extract detailed documentation. We investigated existing solutions, and it turned out that each Vue library had its own mechanism for compiling metadata information, and in some cases one was lacking completely.<\/p>\n

Since we develop in TypeScript and provide IDE support for it as well, we know how useful type definition files<\/a> (*.d.ts.<\/code>) can be. They provide precise information about JavaScript library symbols, which allows IDEs and text editors to deliver relevant code completion, validation, and quick documentation. We wanted something similar for web frameworks, and that\u2019s how we came up with web-types<\/strong><\/a>.<\/p>\n

\"vue3-ts<\/p>\n

What is web-types?<\/h2>\n

Web-types is an open source standard for documenting various web frameworks. In its first iteration, it\u2019s focused only on Vue support. The documentation consists of a single JSON file. The good news is that it\u2019s already supported by some major Vue libraries \u2013 you can get detailed documentation for bootstrap-vue, quasar, vuetify, nuxt.js, and @ionic\/vue while coding in WebStorm.<\/p>\n

Private Vue libraries of many companies are also shipped with web-types. Good in-place documentation \u2013 code completion, validation, and quick documentation \u2013 significantly improves the onboarding process for developers and allows them to quickly learn about new components and their features.<\/p>\n

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.<\/p>\n

\"vue3-ts<\/p>\n

How to build web-types?<\/h2>\n

Building a web-types JSON is relatively easy. A JSON Schema is available here<\/a>, so you have autocompletion and documentation directly in your editor if the file is named web-types.json<\/code>. Usually, though, you\u2019ll 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<\/a> package to generate the file.<\/p>\n

What\u2019s next?<\/h2>\n

We\u2019re 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\u2019t be able to achieve much without support from the community<\/strong>. We\u2019re counting on you to contribute web-types to your favorite Vue libraries. Links to similar PRs can be found here<\/a>.<\/p>\n

The WebStorm team<\/em><\/p>\n","protected":false},"author":967,"featured_media":172839,"comment_status":"closed","ping_status":"closed","template":"","categories":[6711],"tags":[103,2844,6439],"cross-post-tag":[],"acf":[],"_links":{"self":[{"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/webstorm\/108219"}],"collection":[{"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/webstorm"}],"about":[{"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/types\/webstorm"}],"author":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/users\/967"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/comments?post=108219"}],"version-history":[{"count":9,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/webstorm\/108219\/revisions"}],"predecessor-version":[{"id":152708,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/webstorm\/108219\/revisions\/152708"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/media\/172839"}],"wp:attachment":[{"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/media?parent=108219"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/categories?post=108219"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/tags?post=108219"},{"taxonomy":"cross-post-tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/zh-hans\/wp-json\/wp\/v2\/cross-post-tag?post=108219"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}