JSON standard for documenting web component libraries for IDEs, documentation generators and other tools
APACHE-2.0 License
Welcome to Web-Types, a JSON format for documenting web component libraries.
Web-Types is a framework-agnostic format aimed at providing IDEs and other tools with the metadata information about the contents of a component library. Its powerful name patterns allow encoding information about web framework syntax or customizing code completion suggestions for large icon libraries in the IDEs that support Web-Types.
Web-Types started as a format to support Vue libraries, but we've always wanted to provide a more generic solution. Finally, version 2.0 of Web-Types format works seamlessly for any kind of web framework, Web Components library, or CSS icons pack.
A detailed documentation of the format is available here
Starting with version 2021.3.1 of WebStorm (and other JetBrains IDEs), a full support for the new Web-Types format is supported (the new format has been partially supported since 2021.2). You can now add custom HTML elements and attributes, custom CSS classes, properties, functions, pseudo-classes, and pseudo-elements. Vue and Angular support integrates fully with the format, so you can easily mix Web Components in Angular or Vue templates.
Example Web-Types files are available in examples
folder. Web-Types for Angular and Vue frameworks are available
in the examples/references
directory. They require dynamic contributions based on project source from IDE plugins
to work properly.
A webinar recording with Piotr Tomiak explaining the new version of the format and how pattern processing works is available on YouTube.
The new version of Web-Types is backward compatible with the Vue-only Web-Types.
To enable your Web-Types file in the project, link it through the web-types
property of your local project package.json
file.
You can specify multiple Web-Types files by providing an array of paths.
Library providers are welcome to include detailed Web-Types JSONs and link them through web-types
property in package.json
. E.g.:
{
...
"web-types": "./web-types.json"
...
}
Many libraries are providing this feature, for instance:
In case a library is not shipping Web Types, they can be published under the @web-types
scope on NPM.
Currently, the following frameworks and libraries are supported in such a way:
Published JSONs are checked into this repository under the packages
folder. In case of Web-Types published to @web-types
scope,
IDEs are supposed to download required JSONs without any changes to the user project structure.
Various IDEs perform optimizations when scanning node_modules
directory, so to ensure that web-types
for
your package are always available, make sure it's listed in packages/registry.json
.
Web-Types JSON Schema is available in the schema
folder. Use one of the following URLs to reference it in your JSON files:
http://json.schemastore.org/web-types
or
https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json
Currently, the following component documentation formats are supported:
vue-docgen-api
vue-docgen-web-types
package to your projectvue-docgen-web-types
command. You can launch it in a watch mode by passing --watch
and--configFile
parameter.If you're not using JSDoc in your project, you can create your own builder for web-types
JSON. For examples see
vuetify, quasar or bootstrap-vue pull requests from above.
@web-types
scopeWe welcome your PRs with Web-Types for libraries in packages
folder. There should be a single file per library in the format:
packages/<pkg-name>/<pkg-name>@<pkg-version>.web-types.json
We are syncing contents of the packages
folder using script/publish.sh
script which usage syntax is following:
publish.sh <package-name> [--dry-run]
The script scans folder packages/<package-name>
for provided Web-Types jsons and synchronizes
contents with NPM.
@web-types
scopeVersioning and naming rules are as follows:
pkg-name
are available under @web-types/pkg-name
@scope/pkg-name
are available under @web-types/at-scope-pkg-name
1.2.3
are published as prerelease 1.2.3-n
, e.g. 1.2.3-3
1.2.3-rc.1
are published with additional segment,1.2.3-rc.1.3
<pkg-ver
and include prerelease versions,1.2.6
, query package list with <1.2.6
, which can match1.2.4-12
All contributions are welcome! We need your help to improve the Web-Types format specification, to support other frameworks and to improve quality of generated metadata through scripts.