Output Targets

One of the more powerful features of the compiler is its ability to generate various builds depending on "how" the components are going to be used. Stencil is able to take an app's source and compile it to numerous targets, such as a webapp to be deployed on an http server, as a third-party component lazy-loaded library to be distributed on npm, or a vanilla custom elements bundle. By default, Stencil apps have an output target type of www, which is best suited for a webapp.

Output Target Types:

• dist-custom-elements-bundle: Custom Elements
• dist: Distribution
• www: Website
• docs-readme: Documentation readme files formatted in markdown
• docs-json: Documentation data formatted in JSON
• docs-custom: Custom documentation generation

Example:

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'dist'
    },
    {
      type: 'www'
    }
  ]
};

Differential Bundling

It's also important to note that the compiler will automatically generate the numerous bundles in order to support "differential bundling". What this means is that during production builds, Stencil will generate code for both modern browsers, and legacy browsers (IE11) from the same source code. The advantage of differential bundling is that modern browsers can avoid all the polyfills and bloated legacy JavaScript, and use the modern APIs already baked into the browser.

In the example below there are two script tags, however, only one of them will be requested by the user. For IE11 users, they'll download the app.js file which is in the ES5 syntax and has all the polyfills. For users on modern browsers, they will only download the app.esm.js file which uses up-to-date JavaScript features such as ES modules, dynamic imports, async/await, Classes, etc.

Note: buildEs5 must be set to true to generate the IE11 ES5 file

<script type="module" src="/build/app.esm.js"></script>
<script nomodule src="/build/app.js"></script>

Docs Auto-Generation

As apps scale with more and more components, and team size and members continue to adjust over time, it's vital all components are well documented, and that the documentation itself is maintained. Maintaining documentation is right up there with some of the least interesting things developers must do, but that doesn't mean it can't be made easier.

Throughout the build process, the compiler is able to extract documentation from each component, to include JSDocs comments, types of each member on the component (thanks TypeScript!) and CSS Variables (CSS Custom Properties).

Component Property Docs Example:

To add a description to a @Prop, simply add a comment on the previous line:

/** (optional) The icon to display */
@Prop() iconType = "";

CSS Example:

Stencil will also document CSS variables when you specify them via jsdoc-style comments inside your css or scss files:

 :root {
   /**
    * @prop --primary: Primary header color.
    */
   --primary: blue;
 }