Angular Custom HTML Data Parser for Visual Studio Code

VS Code has the capability to load custom web component information into the HTML language services. These language services provide the IntelliSense we use everyday for code completion and functionality discovery. Imagine creating a set of directives and components within an Angular application and seeing those components within VS Code's own code hints.

Well now you can do just that.

This small library can read your Angular application source directory for components and directives and generate custom HTML data for VS Code to consume.

Add it to your build pipelines to keep your data up-to-date. Build extensions for your teams to use and provide built-in documentation around your organization's component system. Include it with your npm packages to enable your end users to keep coding without having to go back to the external documentation.

Disclaimer

This is still a work in progress and new features will be added as necessary. Feel free to use this project however you'd like, just please be sure to give acknowledgement where applicable.

Usage

Generating custom HTML data for VS Code is as simple as:

npx ng-vscode-html-data-parser

The default behavior will look for any *.ts within your package directory and attempt to generate custom HTML data from any components or directives found.

Command Line Options

This library also supports some flags to help provide all of the functionality you need:

[--d, --destination] {outputLocation}

This option will set the output location and filename for the custom HTML data file that's generated by this library. It's suggested that this file name end with ".html-data-.json". VS Code understands this file and will apply the proper JSON schema to it automatically when editing.

By default, this is a file named "custom.html-data.json" in the package directory.

Example

This will write the custom HTML data file to the package directory with the name "my-custom.html-data.json":

npx ng-vscode-html-data-parser --dest my-custom.html-data.json

[--f, --files] {filePattern}

This option will tell the library where to find the Angular component files. This should be in the glob pattern format.

By default, this is all TypeScript files, excluding test files, found from the root package directory (e.g.: **/!(*.spec).ts);

Example

This will chose all TypeScript files found in the "src" directory:

npx ng-vscode-html-data-parser --files src/**/*!(*.spec).ts

Config files

This library supports a separate config file called .ng-html-data.json, which can be used to provide the same functionality available in the command line options. Simply create the json file and fill it with the configuration values necessary:

Example

{
  "destination": "my-custom-html-data.json",
  "files": "src/**/*.ts"
}

The library also supports the usage of a JavaScript module, in a file called .ng-html-data.js, to populate the configuration and provide custom formatters.

Example

module.exports = () => ({
  /**
   * This formatter function is used when the description for an attribute is being compiled.
   * @param jsDoc This is the jsDoc object associated with the input/output property or directive class.
   * @param input This is a boolean that indicates weather or not the attribute has the {@Input} designation.
   * @param output This is a boolean that indicates weather or not the attribute has the {@Output} designation.
   * @returns A string representing the attribute's description.
   */ 
  attributeFormatter: function(jsDoc, input, output) {
    return jsDoc.comment 
      + (input ? '\n\n_@Input_' : '') 
      + (output ? '\n\n_@Output_' : '');
  },
  /**
   * This formatter function is used when the description for a component or element directive is being compiled.
   * @param jsDoc This is the jsDoc object associated with the input/output property or directive class.
   * @returns A string representing the tag's description.
   */
  tagFormatter: function(jsDoc) {
    return jsDoc.comment;
  },  
  destination: 'custom.html-data.json',
  files: '**/!(*.spec).ts'
});

For an example of an attribute formatter, see:

https://github.com/wthomas3/ng-vscode-html-data-parser/blob/main/src/formatters/simple-attribute-description-formatter.ts

The configurations can all be used at the same time, with the order of importance, from lowest to highest being:

• JSON config file
• JavaScript config module
• Command line parameters

Setting up VS Code for Custom HTML Data

Setting up VS Code to use the output files from this library is very easy. Simply open up your folder or workspace settings and add this file to the html.customData setting. You may need to reload VS Code for your changes to take place.

More information on how to set this up can be found here: Custom Data for HTML Language Service

TODO

• Support for components found in type declaration files in precompiled libraries.
• Support enum types.

References

• VS Code Custom Data Overview
• VS Code Custom Data for HTML Language Service
• VS Code Custom Data Schema
• Full VS Code HTML Language Type Definition