Stencil

Stencil is a compiler for building web apps using Web Components. It generates components that target the Web Component standard, meaning its components can be used standalone or inside any React element.

At TIND, we are moving away from Stencil because its build times are increasingly long, and because React is more industry-standard whereas Stencil (somewhat ironically) is not widely used and has fewer resources available for it.

Stencil Component Starter

The following documentation is inspired by this official guide.

Getting Started

To create a new StencilJS component go in the tinduicomponents folder and run the generate command:

cd /code/invenio/tinduicomponents/
npx stencil generate

It will ask for the component name (please look the next section) and other options that you can set all as enabled.

At this point the auto-reload should build the component and make it usable (look the proper section below).

If for some reason it is not the case you can build manually with (still in the tinduicomponents folder):

npm run build

Naming Components

All component uses the dash-case and should be prefixed with the tindui- prefix.

Then it should follow with a category name in order to group all component with a similar purpose e.g.: tindui-button-

Conclude it with the component specific name to distinguish it among all other component in the same cat e.g.: tindui-button-generic or tindui-button-dropdown

If the component is planned to be used in a specific module or situation please indicate it like: tindui-table-result-globallist

Using Stencil components

In order to use the tinduicomponents in your html is required to add the following imports:

<script type="module" src="/js/tinduicomponents/tinduicomponents/tinduicomponents.esm.js"></script>

At this point you can refer to the component using its tag name (that you can find in the auto-generate .tsx file):

<alert-box alert-type="success" message="Component successfully created."></alert-box>

Install additional npm packages

From the modules/tinduicomponents folder:

  npm install <yourpackage> --save

Publishing Stencil components

Although Stencil components live in the same repository as Invenio, it is built and published separately. This allows us to avoid rebuilding Stencil on every instance and instead pull a pre-built version. It is easiest to conceive of Stencil as a separate repository. We host stencil on npm as @tindtechnologies/tinduicomponents.

Because npm uses linear versioning, for simplicity we have CI setup so that you can only modify stencil on the master branch. The CI tooling uses Github Actions.

Developing Stencil

There are two possible approaches.

Instance size t3.large or larger

You can run sudo npm run build.dev on the instance.

Building locally

You need to run npm run build.dev on your local machine. Then you need to modify invenio-refresh-loop.sh to remove this line (possibly line 16):

          --exclude=tinduicomponents/dist \

Now the Stencil components should be copied over whenever they are modified.

We want to make this process nicer in the future.

Modifying Stencil

1. Create a branch targeting master and incorporate any Stencil modifications you want to make.
2. Bump the version in tinduicomponents/package.json and re-lock with npm i.
3. Once the PR is merged, Github Actions should automatically build and publish the new version.
4. Create a branch targeting development, and bump the tinduicomponents version in npmBuild/loose/package.json to what you specified in step 2.
5. Once this PR is merged, the changes should now be reflected.

How does CI work?

• Opening a PR targeting master will run stencil-ci-master.yml. If any modifications were made to Stencil components, it builds them (failing on any errors) and ensures they are formatted according to our Prettier rules.
• Opening a PR targeting any other protected branch (e.g. development, config) will run stencil-ci-other.yml. If any modifications were made to Stencil components, it will error and prevent the PR from being merged.
• Pushing a commit to master (e.g. on a PR merge) will run stencil-publish.yml. If the version in tinduicomponents/package.json does not exist on npm, it will build and publish it. Otherwise it will do nothing.

More

Stencil component official guide.

Using bootstrap css inside components: guide

Please read this article before writing a new component: guide

Common mistakes

• Inline styles needs to be provided as an object:

let styles = {
  width: "45%",
  minWidth: "2em",
};
<div style={styles}></div>;

• Do not set State variables in the render() method.
• For arrays, the standard mutable array operations such as push() and unshift() won't work.
• Define onEvent handler function with the syntax onEvent = () => {}. In this way the component this would be bound automatically.