Getting Started with Stencil @ Esri

Notes I took while telling Mike how to add various useful things to this project

Storybook

Install along with the deps

npm install --save-dev @pxtrn/storybook-addon-docs-stencil @storybook/addon-a11y @storybook/addon-actions @storybook/addon-essentials @storybook/addon-knobs @storybook/addon-links @storybook/react @storybook/storybook-deployer @storybook/web-components

Add Scripts to package.json

"start-storybook": "start-storybook -p 6006 -s ./dist,./public --no-manager-cache", 
"storybook.run": "run-s build start-storybook", 
"storybook": "npm-run-all build --parallel build.watch start-storybook",
"build-storybook": "build-storybook -s ./dist,./public", 
"deploy-storybook": "storybook-to-ghpages"

Copy .storybook folder from https://github.com/Esri/hub-components into your repo. This will pull in calcite-components and a number of other component projects. If you don't want to load them all, edit the .storybook/main.js file and comment out parts of the refs object

Create public and doc folders for storybook's use.

HTML Harnesses

make /src/html edit /src/index.html to have links to the harnesses i.e. ./html/some-folder/some-file.html

edit outputTargets in stencil.config.ts

outputTargets: [
    {
      type: "dist",
      esmLoaderPath: "../loader",
      copy: [{ src: "**/*.i18n.*.json", dest: "assets/i18n" }],
    },
    {
      type: "dist-custom-elements-bundle",
    },
    {
      type: "docs-readme",
    },
    {
      type: "docs-json",
      file: "dist/docs.json",
    },
    {
      type: "www",
      serviceWorker: null, // disable service workers
      copy: [
        {
          src: "./html/**/*.html",
        },
        {
          src: "../node_modules/@esri/calcite-components/dist/calcite",
          dest: "calcite",
        },
        { src: "**/*.i18n.*.json", dest: "assets/i18n" },
        {
          src:
            "../node_modules/@esri/calcite-components/dist/calcite/assets/calcite-date-picker/nls",
          dest: "calcite-date-picker/nls",
        },
      ],
    },
    {
      type: "docs-vscode",
      file: "custom-elements.json",
    },
  ],

I18n

Esri is building a set of Stencil Utils for i18n - but that's still in progress. Until it's ready, it's best to copy the utilities from hub-components

Copy /src/utils/localization and /src/utils/stencil-intl from https://github.com/Esri/hub-components/tree/beta/src/utils into your project

Usage Guide: https://esri.github.io/hub-components/?path=/story/guides-localization--page

For setting up storybook, I'd recommend npx sb init even though storybook doesn't have an official adapter for stencil.

This is the guts of a message I sent to Dhrumil about setting up storybook in a stencil project:

As far as I can tell, there isn’t clarity on the “right” way to setup storybook in a stencil project. There has been some discussion (https://github.com/storybookjs/storybook/pull/15479, https://github.com/storybookjs/storybook/pull/15479) but it kinda seems to have stalled. We are using the @storybook/web-components “adapter” which works pretty well but not perfectly with stencil. I am not certain but I think you would end up with a setup similar to ours if you run npx sb init in your stencil project and choose “web-components” when prompted for the project type. An alternative (and I believe this is how calcite-components is setup) is to choose “html” as the project type. If you go with the web-components adapter, I think you will find you need to do a few more things:

You will also need to install lit-html.

I believe you will need to add code to the top of preview.js like this:

import { defineCustomElements } from '../loader';
defineCustomElements(window);

And in order for it to be able to find that loader, you will need to have done a build of the stencil project.

Esri / solutions-components