@stencil-community/web-types-output-target

Stencil Web Types Output Target

A Stencil output target for generating web types to provide intellisense for Stencil components in HTML and Vue files.

[!NOTE] This package follows semantic versioning. Small breaking changes to the API may occur prior to hitting v1.0.

Overview

One of the core features of web components is the ability to create custom elements. When Stencil compiles a project, it generates a custom element for each component in the project.

By default, integrated development environments (IDEs) like JetBrains' WebStorm are not aware of a project's custom elements. This causes the IDE to often warn developers that it doesn't have any information about their custom elements, and results in a poorer development experience. In order to enable more intelligent features in JetBrains products, such as auto-completion, hover tooltips, etc., developers need to inform it of their project's custom elements.

The webTypesOutputTarget output target tells Stencil to generate a JSON file containing this information.

This is an opt-in feature and will write a JSON file containing web types in a directory specified by the output target. Once the feature is enabled and your IDE is informed of the JSON file's location, writing code in HTML and Vue files will have similar intellisense to that of TSX files.

Set Up

The output target is not built into Stencil itself. It's a third party package, that needs to be installed as a dev-dependency:

$ npm i --save-dev @stencil-community/web-types-output-target

To generate custom element information for JetBrains IDE's, add the webTypesOutputTarget output target to your stencil.config.ts:

import { Config } from '@stencil/core';
import { webTypesOutputTarget } from '@stencil-community/web-types-output-target';

export const config: Config = {
  outputTargets: [
    webTypesOutputTarget(),
  ]
};

Stencil will write a web-types.json to your project's root directory the next time the Stencil build task is run.

Configuration

The webTypesOutputTarget output target takes an optional argument, an object literal to configure the output target. The following are properties on that configuration object.

outFile

Defaults to StencilConfig#{rootDir}/web-types.json.

Since v0.3.0.

Description: A string that represents location of the file generated by this output target. Users may specify any of the following:

• A relative directory (e.g. '../')
• A filename (e.g. 'my-types.json')
• A relative directory ending in a filename (e.g. '../my-types.json').

It is not recommended to use absolute paths for this setting, as this can cause errors in projects shared by more than one developer/environment. An error will be logged to the console if an absolute path is detected.

Any relative file path provided will be relative to the 'root directory' of your Stencil project. By default, this is the directory your project's stencil.config.ts is in.

If the value provided does not end in '.json', the output target assumes that a filename must be added to the path. In such cases, the default name, 'web-types.json', will be added to the path:

• ../ will be transformed to ../web-types.json
• ./web-types will be transformed to ./web-types/web-types.json
• ./my-types.json will not be transformed, as the provided value ends in '.json'

Using Web Types

Once web types have been written to disk, they need to be picked up by the IDE. Web types for your project can be picked by JetBrains IDEs by setting the web-types property at the root level of your project's package.json file:

{
  "name": "your-projects-name",
  "version": "1.0.0",
  "//": "Other details omitted",
  "web-types": "./web-types.json"
}

Having this file locally on disk will allow your JetBrains IDE to pick up additional typings automatically. To provide these IDE-specific typings to users of your library, be sure to include the generated web types file in your package's distributable by adding it to your package.json#files array.

References

https://plugins.jetbrains.com/docs/intellij/websymbols-web-types.html#file-structure