Angular Integration with Stencil | Stencil

Stencil can generate Angular component wrappers for your web components. This allows your Stencil components to be used within an Angular application. The benefits of using Stencil's component wrappers over the standard web components include:
The following table shows the compatibility between @stencil/angular-output-target versions and Angular versions:
We recommend using a monorepo structure for your component library with component wrappers. Your project workspace should contain your Stencil component library and the library for the generated Angular component wrappers.
An example project set-up may look similar to:
This guide uses Lerna for the monorepo, but you can use other solutions such as Nx, Turborepo, etc.
To use Lerna with this walk through, globally install Lerna:
If you already have a monorepo, skip this section.
If you already have a Stencil component library, skip this section.
In the packages/ directory, run the following commands to generate a Stencil component library:
If you already have an Angular component library, skip this section.
The first time you want to create the component wrappers, you will need to have an Angular library package to write to.
In the packages/ directory, use the Angular CLI to generate a workspace and a library for your Angular component wrappers:
You can delete the component-library.component.ts, component-library.service.ts, and *.spec.ts files.
You will also need to add your generated Stencil library as a peer-dependency so import references can be resolved correctly:
For more information, see the Lerna documentation on package dependency management.
The Angular CLI will install Jasmine as a dependency to your Angular workspace. However, Stencil uses Jest as it's unit testing solution. To avoid type definition collisions when attempting to build your Stencil project, you can remove jasmine-core and @types/jasmine as dependencies in the Angular workspace package.json file:
Install the @stencil/angular-output-target dependency to your Stencil component library package.
In your project's stencil.config.ts, add the angularOutputTarget configuration to the outputTargets array:
The componentCorePackage should match the name field in your Stencil project's package.json.
outputType should be set to 'component' for Stencil projects using the dist output. Otherwise if using the custom elements output, outputType should be set to 'scam' or 'standalone'.
The directivesProxyFile is the relative path to the file that will be generated with all of the Angular component wrappers. You will replace the file path to match your project's structure and respective names. You can generate any file name instead of components.ts.
The directivesArrayFile is the relative path to the file that will be generated with a constant of all the Angular component wrappers. This constant can be used to easily declare and export all the wrappers.
See the API section below for details on each of the output target's options.
You can now build your Stencil component library to generate the component wrappers.
If the build is successful, you will now have contents in the file specified in directivesProxyFile and directivesArrayFile.
You can now finally import and export the generated component wrappers for your component library. For example, in your library's main Angular module:
Any components that are included in the exports array should additionally be exported in your main entry point (either public-api.ts or index.ts). Skipping this step will lead to Angular Ivy errors when building for production. For this guide, simply add the following line to the automatically generated public-api.ts file:
The default behavior for this output target does not handle automatically defining/registering the custom elements. One strategy (and the approach the Ionic Framework takes) is to use the loader to define all custom elements during app initialization:
See the documentation for more information on defining custom elements using the dist output target, or update the Angular output target to use dist-custom-elements.
If you are using a monorepo tool (Lerna, Nx, etc.), skip this section.
Before you can successfully build a local version of your Angular component library, you will need to link the Stencil package to the Angular package.
From your Stencil project's directory, run the following command:
From your Angular component library's directory, run the following command:
The name of your Stencil package should match the name property from the Stencil component library's package.json.
Your component libraries are now linked together. You can make changes in the Stencil component library and run npm run build to propagate the changes to the Angular component library.
As an alternative to npm link , you can also run npm install with a relative path to your Stencil component library. This strategy, however, will modify your package.json so it is important to make sure you do not commit those changes.
If you already have an Angular app, skip this section.
From your Angular workspace (/packages/angular-workspace), run the following command to generate an Angular application with modules:
This section covers how developers consuming your Angular component wrappers will use your package and component wrappers in an Angular project using modules.
In order to use the generated component wrappers in the Angular app, you'll first need to build your Angular component library. From the root of your Angular workspace (/packages/angular-workspace), run the following command: