2022.3+

Web Types

File Structure

The Web Types file should, at least, contain name, version and contributions properties. It should also include $schema property which can be either https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json or http://json.schemastore.org/web-types. The schema contains detailed documentation for all the JSON entities.

Directly under contributions property are listed namespaces with their contributions. Currently only html, css or js namespaces are allowed. However, in the future this limitation will be lifted to support Web Types for other technologies.

The namespace object contains symbol kind names listed as properties. Some symbol kinds are predefined and directly supported by IDE (see Direct Support for reference). The kind of symbol should be related to its role. For instance, a Vue directive should be of the kind vue-directives. Each framework should define a set of custom symbol kinds if needed. Reference for the most important symbol kinds defined by frameworks supported by IDEs is below.

Each symbol kind name property of a namespace object is an array of symbol contributions. A symbol contribution should have at least a name. Contributions in addition to standard properties can define sub-contributions and custom properties. A custom property is a JSON property, whose value is of a simple type (string, number or boolean), or is an array of simple types. If a contribution’s JSON property’s value is an object value or an array of objects, it is treated as a list of sub-contributions. Such contributions will be assigned to the same namespace as the parent contributions. To use a different namespace for sub-contributions, nest symbol kind JSON property name under a js, css or html property, e.g.:

{
  "contributions": {
    "html": {
      "elements": [
        {
          "name": "my-element",
          "description": "A custom HTML element",
          "attributes": [
            {
              "name": "foo",
              "description": "A custom HTML attribute of `my-element`"
            }
          ],
          "css": {
            "properties": [
              {
                "name": "--bg-color",
                "description": "Background color of my-element"
              }
            ]
          }
        }
      ]
    }
  }
}

In the example below, Web Types contributes information that the my-element HTML element supports a custom CSS property --bg-color. The attributes are implicitly under the html namespace. To contribute a foo attribute, one could also write it in longer form:

{
  "name": "my-element",
  "description": "A custom HTML element",
  "html": {
    "attributes": [
      {
        "name": "foo",
        "description": "A custom attribute of `my-element`"
      }
    ]
  }
}

Each Web Types contribution is represented in the Web Symbols framework by a PsiSourcedWebSymbol object. All the Web Types contributions are mapped one-to-one, and custom properties are accessible through properties property.

Including Web Types

Web Types can currently be discovered by the IDE in the following ways:

NPM

The IDE will automatically discover any Web Types shipped with the NPM library and specified in the web-types property of package.json. The property accepts a string or an array of strings with relative paths to Web Types files shipped with the package.

Local Project

In your JavaScript projects in package.json files, you can specify web-types property similarly to the NPM package. The property accepts a string or an array of strings with relative paths to Web Types files within the project.

IDE Plugin

You can ship Web Types JSON with your IDE plugin. To point an IDE to its location, use com.intellij.webSymbols.webTypes extension point and pass the file location in source attribute value. With enableByDefault attribute, you can choose whether the Web Types file should be contributed to Web Symbols scope by default, or only if an NPM package with the same name is present in the project.

Special Properties

inject-language

Supported by html/elements and html/attributes, allows to inject the specified language into HTML element text or HTML attribute value.

doc-hide-pattern

If a symbol uses a RegEx pattern, usually it will be displayed in a documentation popup section "pattern". Setting this property to true hides that section.

hide-from-completion

By default, all symbols show up in code completion. Setting this property to true prevents a symbol from showing up in the code completion.

Symbol Kinds

Web Types files are used internally by IDEs and tools to define rules for frameworks. Following is the reference for symbol kinds used by framework support.

{
  "ng-custom-events": [
    {
      "name": "Custom modifiers for declarative events handling",
      "priority": "normal",
      "pattern": {
        "template": [
          {
            "items": {
              "path": "/js/events",
              "includeVirtual": false
            }
          },
          {
            "items": "ng-event-plugins-modifiers",
            "template": [
              ".",
              "#...",
              "#item:modifiers"
            ],
            "priority": "high",
            "repeat": true,
            "unique": true,
            "required": false
          }
        ]
      },
      "ng-event-plugins-modifiers": [
        {
          "name": "prevent"
        },
        {
          "name": "stop"
        }
      ]
    }
  ]
}

{
  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
  "name": "Cool library",
  "version": "1.0.0",
  "js-types-syntax": "typescript",
  "description-markup": "markdown",
  "contributions": {
    "html": {
      "elements": [
        {
          "name": "cool-component",
          "description": "Use the cool component to make your website more attractive.",
          "doc-url": "https://example.com/docs/cool-component",
          "attributes": [
            {
              "name": "color",
              "description": "Choose color for coolness",
              "default": "blue",
              "required": false,
              "doc-url": "https://example.com/docs/cool-component#attrs",
              "value": {
                "type": "string"
              }
            }
          ],
          "slots": [
            {
              "name": "container"
            }
          ],
          "events": [
            {
              "name": "color:changed",
              "description": "Emitted when color changes"
            }
          ],
          "js": {
            "properties": [
              {
                "name": "color",
                "type": "string",
                "default": "blue"
              }
            ]
          },
          "css": {
            "properties": [
              {
                "name": "--cool-degree"
              }
            ]
          }
        }
      ]
    }
  }
}