event-listener-types-output-target

Stencil output target to generate event listener types

Summary

Stencil components currently don't generate event listener types which can make consuming Stencil components difficult when wanting to add an event listener in a TypeScript project:

const myComponent = document.createElement('my-component');

myComponent.addEventListener('my-event', event => {
  // TypeError: Property 'detail' does not exist on type 'Event'
  event.detail;
});

This target output generates additional types to make events type safe:

const myComponent = document.createElement('my-component');

myComponent.addEventListener('my-event', event => {
  // event is now of type MyComponentCustomEvent, and detail will
  // have the proper type
  event.detail;
});

This will also allow components to have proper Output binding types in Angular projects:

@Component({
  selector: 'app-root',
  template: `<my-component (my-event)="handleMyEvent($event)" />`,
})
export class AppComponent {
  handleMyEvent(event: MyComponentCustomEvent<string>) {
    // event is properly typed now and can be consumed without
    // needing to type `event` as Event or any then use type assertion
    // to its proper type
    event.detail;
  }
}

How to use

To export event listener types:

1. Install event-listener-types-output-target
2. Update Stencil config to include eventListenerTypesOutputTarget
3. Add component-event-listeners.d.ts to index file

Install event-listener-types-output-target

npm i -D event-listener-types-output-target

Update Stencil config

By default your Stencil config should be located at stencil.config.ts. Update your Stencil config to use this output target:

import { Config } from '@stencil/core';
import { eventListenerTypesOutputTarget } from 'event-listener-types-output-target';

export const config: Config = {
  // ...
  outputTargets: [
    // ...
    eventListenerTypesOutputTarget(),
  ],
};

Now when you build, component-event-listeners.d.ts will be generated next to your components.d.ts file found at src/component-event-listeners.d.ts.

This is where components.d.ts is generated by default, but you can override where the component-event-listeners.d.ts files are generated by setting outputPaths:

import { Config } from '@stencil/core';
import { eventListenerTypesOutputTarget } from 'event-listener-types-output-target';

export const config: Config = {
  // ...
  outputTargets: [
    // ...
    eventListenerTypesOutputTarget({
      outputPaths: ['some/custom/path/component-event-listeners.d.ts'],
    }),
  ],
};

Add types to index.ts

To include component-event-listeners.d.ts in your dist, you can add the generated types to your index.ts found at src/index.ts:

export * from './components';
export * from './component-event-listeners'; // <-- add this line
// ...

You'll get a type error if component-event-listeners.d.ts doesn't already exist, so be sure to generate one or add a placeholder like this one:

/** src/component-event-listeners */
// Doesn't matter what you export, but this file will need to export/import something something
export type Placeholder = 'This should be replaced automatically';

Output target options

For more custom behavior such as changing the outputPaths to customize where the generated types files are saved, there are two other options:

1. outputPaths - Paths where generated event listener types will be stored. Path should include filename. Default if not defined is:

   ['src/component-event-listeners.d.ts'];

2. importPath - The generated event listener types depend on types from components.d.ts. Setting this will define the path where those types will be imported from. Default if not defined is:

   './components';

3. excludeComponents - List of components to not generate event listener types. Values should be the tag name of the component.

Development

For development, code changes are lint/formatted on commit. New features should come with new tests.

npm i # Install dependencies
npm run test # Run unit tests
npm run test.watch # Run unit tests in watch mode