DEV Community: Tally Barak

Writing Storybook Stories with TSX for Stencil

Tally Barak — Mon, 09 May 2022 10:34:01 +0000

Yes, you can!

If you want to write your stencil stories for storybook using TSX (the Typescript version of JSX), this is actually possible. A bit of tweaking, and you should go to go.
BUT - this is still a very preliminary work, and I expect it to suffer quite few bumps in different scenarios. Nevertheless, I thought it it worth sharing, as I know people were looking for a solution.

This is assuming you are using the html version of Storybook with Stencil. You can find a working version in my stencil-one demo repo. (This is my demo repo for unit testing in Stencil, so feel free to look around).

These are the main versions I worked with. I have no idea if it will be compatible with other versions.

Stencil: 2.15
Storybook: 6
webpack: 5
babel-loader: 8

Step 1: Write your story

This is what a story should look like, using CSF3 (Component Story Format). Obviously, it should be in a file named .tsx, so it will go thru the right tooling. Also, change the path that looks for your stories to include .tsx files. (stories option in the main file).

/** @jsx h */
/** @jsxRuntime classic */

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

export default {
  title: 'My Basic',
};

export const Default = {
  render: () => (<my-basic first="Millie" last="Brown"></my-basic>)
};

Note the @jsx directives. They seem to be necessary.

Step 2: Configure Webpack for jsx

We are going to tweak .storybook/main so it will include the babel jsx transformer. In order to do that we will find the rule that handles tsx and add the @babel/plugin-transform-react-jsx as plugin with the pragma: {'h'}.

  webpackFinal: async (config) => {
    const tsxRule = config.module.rules.find(rule => 'a.tsx'.match(rule.test));

    if(tsxRule) {
        const options = tsxRule.use[0].options;
        options.plugins = [
          ['@babel/plugin-transform-react-jsx', {
            prgama: 'h'
          }],
          ...options.plugins
        ];
    }
    return config;
  }

Step 3: Render the stories using Stencil's renderVDom

The last part is changes to the storybook/preview code. Create a function that will be used as a decorator and will render elements to the DOM.

const stencilWrapper = (storyFn, context) => {
  const host = document.createElement('div');
  stencilClient.renderVdom(
    {
      $ancestorComponent$: undefined,
      $flags$: 0,
      $modeName$: undefined,
      $cmpMeta$: {
        $flags$: 0,
        $tagName$: 'div',  
      },
      $hostElement$: host,
    },
    storyFn(context)
  );
  return host.children[0];
}

And then activate it:
addDecorator(stencilWrapper);

You will also need to make sure that you are calling the defineCustomElements (which you should, anyway) in the preview code or the preview-manager html file.

As mentioned above, this is still prone to errors. If you have any suggestions, improvements, bugs fixes etc, please comment.

Lerna Graph

Tally Barak — Tue, 01 Sep 2020 05:36:11 +0000

If you are using Lerna or have a monorepo that is compliant with Lerna structure - this is a Github Action you would love.

The action generates a graph for all the Lerna packages in the repo and their current version.

Important!!!
Even if you do not use Lerna, you can simply add a lerna.json file with minimal configuration (packages, version) and the action will work!

You can find this action in the marketplace

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

Tallyb / lerna-graph-action

Github action to generate a lerna graph

Lerna Graph Action

This action generates a graph of all Lerna packages in their current version:

Usage:

See parametes in action.yml

Persist the graph on Github artifacts to view them later

steps:
- uses: actions/checkout@v2

- run: mkdir -p graph

- name: Lerna Graph
- uses: lerdajs/lerna-graph-action
  with: 
    rootPath: .
    path: graph/image.png

- uses: actions/upload-artifact@v2
  with:
    name: lerna graph
    path: graph/image.png

FAQ

Do I need to use Lerna for this action?

This action can work with any repository that is compliant with Lerna structure (i.e. multiple package.json files). You do not have to use Lerna to install or publish the packages. The only requirement is have a lerna.json file that marks your packages folders.

View on GitHub

Additional Resources / Info

You cannot go more meta than this: Lerna project graph generated by this action

Deep dive into Monorepos

Tally Barak — Mon, 01 Jun 2020 17:44:28 +0000

What are the best tools to use with a monorepo? As with any other software design consideration, the answer is - it depends on what you need.
But when we talk about monorepo, we should also clarify what a monorepo is. Too often, when discussing mono-repo, the answers resemble the people in the image on the cover of this article.

Allow me to share a few thoughts and clarification on this.

What's inside a monorepo?

The one commonality for all mono-repos is that somewhere in their folder structure, you will find multiple package.json files, each with its own name. So, while we commonly use the term mono-repo, an adequate term is probably a multi-package repo.

The "monorepo" (and now quotes are appropriate) may contain all of your company projects, or can just have a single project broken into packages.

Look under the Facebook GitHub organization and you will find that most of their open-source projects, such as Jest, React, CRA, Docosaurus, are built as monorepo. So clearly, this is not a mono (single) repo, but poly (multi) repos.

So your initial consideration should be the scope of your monorepo. Your monorepo may contain:

All of the organization's backend and front end applications
Your backend applications or microservices and their shared code split into packages.
Utilities shared between your backend and frontend applications (.e.g types, schemas).
Components shared between multiple frontend applications (such as design system)

Goals

Next, you should consider the goals you are trying to achieve by using a multi-package repo. Some of the answers are:

Increase code quality using small loosely-coupled units
Publish packages independently
Decrease installation footprint at the consumer (i.e. install package X only if I consume it. Select between installing package Y and Z)
Reduce maintenance overhead across repos
Reduce build / CI time by JIT building and testing.

It is essential to decide where you are heading as this impacts the decisions you make later.

Organizing a monorepo

I found three dimensions that impact the organization of the mono repo.

a) Installation (bootstrapping)
b) Development flow
c) Publishing

Installation

In multiple packages repo, each package.json contains its NPM packages dependency. The dependencies include runtime dependencies (i.e., dependencies) and development time dependencies (devDependencies).

The two methods for installing the dependencies are:

Install in a node_modules folder inside each package
Install all shared node_modules in the root of the project, and only packages that their versions collide inside each package.

The latter method is called "hoisting," and it is working because of node package resolution algorithm. When resolving modules, the process "bubbles" until it finds the packaged.

Hoisting npm packages is useful in saving time and disk space. (As we all learned, node_modules are the heaviest object in the universe.)

Installing local node_modules ensures that the package correctly defines its requirements in the package.json manifest. It can also avoid the cases of phantom dependencies and doppelgangers.

The standard tools to enable NPM hoisting are Lerna and Yarn (using workspaces). Lerna supports hoisting also for NPM, but in general, is doing a lesser job than Yarn.

Development workflow

The package.json must include the runtime dependencies for each NPM package (or else it will fail to run).
But what about the development dependencies?

There are two main options on how to build and test our packages:

Centralized development
Federated development

Centralized

In a centralized development, the development tools are only
installed and configured once.

├── babel.config.json
├── jest.config.js
├── node_modules
│   ├── jest
│   └── typescript
├── packages
│   ├── package-a
│   │   └── package.json
│   └── package-b
│   └── package.json
└── tsconfig.json

Test configuration, for example, will point to search all of the .spec or .test files all over the repository and run them.
Build can run centralized but need to generate a build directory for each package (for publishing it). In some cases, you may need to create dedicated scripts to achieve this.

A centralized development workflow is useful when building multiple packages that use the same technology. In such a case, it reduces the maintenance overhead, as there is only a single place for configuring the workflow.
A centralized workflow can become a maintenance nightmare if you are adding multiple different technologies.

Autonomous workflow

In a federated workflow, each package is autonomous in the tools, process, and configuration it uses. Here is an example of such a folder structure:

└── packages
├── package-a
│   ├── jest.config.js
│   ├── node_modules
│   │   ├── jest
│   │   └── typescript
│   ├── package.json
│   └── tsconfig.json
└── package-b
├── babel.config.json
├── node_modules
│   ├── babel
│   └── mocha
└── package.json

A decentralized model supports heterogeneous packages, such as backend and frontend applications. This comes with the price tag of higher maintenance overhead.

Lerna can be used to support both workflows. Lerna supports autonomous workflow by specifying each command separately in each package.json and running it centrally using the lerna run command. It can also run ad-hoc commands using the lerna exec syntax.
Nx takes a slightly different approach by using a centralized configuration file (workspace.json, heavily inspired by angular cli configuration) and specifying a dedicated toolchain for each package.
Bazel is another tool that supports monorepo development workflow. Bazel not only decentralized the workflow process but can harness multiple machines to work concurrently. Bazel is suited for very large mono-repos, and can easily become overkill for smaller ones.

Publishing

The last part of using the package is publishing it to a public or private NPM registry. Packages published to a registry are versioned. You can publish all packages with a single version or each package with its own version. Publishing a version also implies publishing a changelog. According to the method selected, there will be a single changelog for all packages or a separate one for each published package.

Lerna is probably the leading tool for multi-package publishing (in fact, this is what the Facebook repos are using it for). Under the hood, Lerna uses Npm and Yarn pack and publish commands.

Conclusion

Deciding to go "monorepo" is only the first step in the journey. It derives a set of further decisions to optimize the repo for the specific project needs.

Documentation made nicer with visuals

Tally Barak — Mon, 17 Feb 2020 13:29:12 +0000

8 months ago I have joined bit.dev as head of the developer's experience. One of the first tasks I had on my plate was a major facelift for our documentation site.
Bit.dev is a revolutionary product and requires people to understand its mental model to be successful in implementing it. For me, that meant good documentation with plenty of drawings. Diagrams and visuals are the best tools in documentation when trying to convey complex concepts. Today bit.dev documentation site has multiple visuals reducing the time it takes for the developers to learn the tool.

Let me share some of the tips on building those visuals that worked well for me during this process.

Grab ideas from design meetings

What should be in the diagrams? Here is a tip that can work pretty well: pick the papers that fell during design meetings. When people are explaining the concepts of their work, this is probably the best diagram that will help someone from the outside to understand what they are talking about. Grab your mobile and take a photo of the paper sketches and the whiteboards. These diagrams are the skeleton for your future visuals.

Be independent

Transforming those sketches into documentation level visuals require some graphical skill. Naturally, this means that we rely on the designer in our company or team. This method did not really work for me. I needed to be independent and to quickly change my diagrams as well as creating new diagrams when ideas pop up.
Sadly, this means that I had to use a lot of the designer time to come up with an idea, review it with the designer, proof-read his work and restart the whole process when I wanted to change something.

Soon enough I decided to put my faith in my own hands which led to the next two tips...

Get inspired by designers

Unless you have a degree in graphical design (in addition to technical and literature degree), there are probably quite a few things you do not know about design.
It is best then to ask the designer for an initial version and start working from that point. Notice the little tricks the designer made: line endings, backgrounds and so on.

In the diagram above I combined some of the elements created by our designers, such as the element depicting a component or the light background. I used those tricks in all of my next designs based on this initial inspiration.

Use a simple tool

If you feel comfortable with Sketch or Photoshop - go ahead. Those tools are extremely powerful. However, you can achieve great results in diagraming with much simpler tools. I decided to use Google Slides. It is easy to use, easy to share (Google, you know...), and can export the diagrams the drawing in png, jpg or even SVG format with ease.

Be consistent

Last but not least, is to keep consistency. There is something very pleasant about consistency, and the readers are more likely to feel at home when the diagrams follow a standard format.
Using a standard color palette, typography, shapes, and metaphors make the reader feel at home when they browse through your documentation.
I put all my drawings in a single slideware, so I have all the colors and shapes in place and I can easily copy what I need between my drawings.

I hope these simple tips will encourage you to also add diagrams to your documentation. After all, we are all attracted to nice colors and shapes.

The Digest Guide to React Styling

Tally Barak — Tue, 17 Dec 2019 17:19:50 +0000

Are you confused over the different styling approaches for components in React? So am I.
To avoid verbosity, I summed it up in 5 bullet points and 4 images, with some footnotes.
Use this article as a starting point for exploring deeper with a basic understanding of how each method works.

CSS in the DOM

Here is how you can add styles to a web page:

External stylesheet

<link rel="stylesheet" type="text/css" href="mystyle.css">

The styles are global and applied on the whole DOM

Embedded (internal) stylesheet:

<style>
   p {
        font-family: georgia, serif; 
        font-size: x-small;
    }
</style>

Also here, the styles are global and applied on the whole DOM

Inline styles

<h1 style="color:blue;">This is a Blue Heading</h1>

The style is local and impacts only the element

Scoped CSS - deprecated!

https://caniuse.com/#feat=style-scoped

Shadow DOM CSS

It is a style tag that only applied to the shadow DOM part where it is included.

CSS in React

Let's see how React styles are translated to the above (internal and external stylesheet and inline styles):
General note: Any .CSS file bellow can also be a CSS with pre-processor such as Less or Scss file.

Basic Styling

With styles

With classes

Styling is processed during build time.
Styles can be exported to an external stylesheet.
Dynamic styling can be achieved using changing inline styles or applying dynamic classes.

CSS Modules

Styles are created during build time (Webpack)
Styles can be exported to an external stylesheet.
In Create-React-App CSS modules are differentiated from regular CSS by adding the .module.css suffix to the files. Webpack configuration in CRA refers to this suffix.

CSS in JS

Styles are created during runtime.
Some libraries allow extracting static CSS parts to external CSS stylesheet (critical CSS).
In CSS in JS JS objects are playing the role of classes.

The DOM Quest

Tally Barak — Sat, 19 Oct 2019 14:43:37 +0000

I had some experience in Angular and recently had to work with Vue and React.
[In case you are worried, this is not one of the Gazillion posts comparing Angular and React with a clear agenda hidden behind some pseudo-objective facade].

I was used to working with Angular in a certain way and was really surprised the first time I inspected the DOM of the React app.

There were no components!

Look at the 3 images below: the first one is... Wait. give it a try yourself to see which one is each. All apps are built with similar components and are based on standard CLI bootstraps.

Image 1:

Image 2:

Image 3:

[The 3 applications are part of the Bit beginners tutorial. You can find their code here: Angular, React and Vue. ]

Did you guess? The first one is React, the second Angular and the last one is Vue.

Here is something to note on the Angular app: it has elements called: <app-root>, <app-top-bar> and <app-product-list>. The 3 components that are defined in my application. The Vue and React app have some hints with classes and ids, but effectively they are just using <div>s.

So what are those Elements?

They are clearly HTML elements. You can select them in the browser's console:

And then do the usual things - attach events, click and so on.

Are they Web Components?

Asks the savvy reader. Let's find out. The MDN Web docs explains Web Components:

Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.

The 3 aforementioned technologies are:

Custom Elements
Templates
Shadow DOM

Let's check each one of them:

Custom Elements

Custom Elements are defined using the CustomElementRegistry.define(). The define function also has a getter that is returning the constructor of the custom element by its name. So, if our component is a custom element querying the window.CustomElements.get should return its constructor.

Templates

If templates are defined, they should exist as a tag inside the DOM. They will not be rendered, but they still exist. So all we need to do is search for the <template> tag on our HTML source.

Shadow DOM

Elements that have a shadow DOM have the shadowRoot attribute set. In Chrome this attributes is visible on the DOM. It is not searchable, but visible on the DOM.
[Another method to identify shadow DOM is to try and select elements that are located inside the shadow DOM. Those elements are not available if you try and run `$('name-of-element')]

If we look at this example from MDN and check those criteria:

Running the same tests on our Angular app will result in failure in all three tests.

So - they are not web components, and nor just custom elements.

HTML Elements

Turns out that the answer is simple - they are just plain HTML Elements. Apparently, you can use any name as to attach elements to the DOM, not just the tags you are familiar with such as Div, P or H1.

So how does a <foo></foo> differs from <div></div> and <input/>?

HTML elements (or tags) are split into categories. This link shows the different categories. (on a personal note I must say that this seems like a specification that is dragging a lot of legacies that no one was willing to touch).

A slightly more clear definition is the interface the elements implement.
All HTML elements conform to the HTMLElement interface. This is the div and foo elements. This interface contains properties such as innerText or events like click. (For the sake of accuracy, the click event is implemented on Element, as it is applicable to other elements such as SVGElement). The input tag, on the other hand, is implemented using the HTMLInputElement interface that extends the standard for the specific functionality an Input element has.

What is it good for?

I could not really find any reference to why this design decision made by the Angular team. But if you think about it, Angular is Google who is the promotors of Web Components (yes, Polymer...). Also, with Angular Elements and the ability to add shadow DOM to an Angular component, this decision is pretty straightforward. If you have an inside view on the Angular decision, feel free to share.

I found that having the component as an element on the DOM is extremely useful in at least three cases:

Debug: just viewing the element on the DOM, on any browser, without the need to add an extension, can really reduce the debug time.
Testing: When you write tests to a component, especially E2E tests, finding an element on the page by its tag name is probably the easiest thing to do.
Styling: This is a topic for a whole other discussion, but it is quite easy to style my-component .container without the need to create special hashes for each component.

Conclusion

The differences between frameworks are sometimes deeper than we think and much less discussed. I was curious to understand how exactly the elements in Angular are built. Researching for this article has led me to some areas less known to humankind. The HTML elements categories section is just one of them.

If you found any mistakes that I made or have some additional light to shed on this, do not hesitate to leave a comment.

If you learned something new, it is great to also leave a comment, or just like it.

When to Use Global NPM Installs? Rarely

Tally Barak — Wed, 09 Oct 2019 10:22:11 +0000

It is widespread to go on a quick start page of some tool and utility and find instructions similar to this one:

npm install - global cool-package
cool start

This command is likely to work, but the --global should make your eyebrow rise. It is barely needed or recommended to install packages globally.

Well, Why Not?

There are a few reasons for you to avoid installing packages globally:

But it works for me…

Who of us, developers, have never heard this? Your colleague is trying to run something you just told them to, and… fails. But it works for me, you tell them.
Global packages can be it. If you have some package they do not have, or if there is a version mismatch between your machines, that might be a problem here.

CI is failing

That problem is similar to the machine mismatch described above. You are setting a CI that is trying to run a command, but it cannot find it. The reason is that the command was part of a package installed locally on your machine.

That version does not work

One of the worst problems when relying on global packages is version compatibility. If you are working on multiple projects, you are likely to have different versions of packages. Version 3 for project A and version 4 for project B. Sadly, only a single version can be installed globally. You need to work this out.

Oh, a new node version!

Are you using nvm to manage your node versions? (and if you do not - have a look at it. It is awesome!). If you switch to a new version of a node, even a minor change, your global packages are gone. If you are a very careful maintainer, you will be using the option --reinstall-packages-from=default. But if you are like me, you will find sometime later that a specific command does not work, and realize you did not migrate your packages.
Minimizing the number of packages can surely save some precious time.

OK, I am convinced. I will try to avoid using global packages. What is the recommended way to work?

Keep Them Local

In most cases, you should keep your packages local to your projects. Save all the packages needed for a project locally with the compatible version or versions range.

npm install --save cool-package
or
yarn add cool-package

But this raises an issue: when you install a package globally, you can easily run it by typing its executable name:

cool start

If you try to do that in a local package, you will get an error that the command was not found. NPM installs the executable under the node_modules/.bin folder. When running a command, the shell does not search on this path. The NPM global path, on the other hand, is added to the shell path (run echo $PATH to view it).
There are a few ways to solve this:

Run the command via npm script.

Define the command in the npm script:

{
"name": "my-package",
"scripts": {
"build": "cool build",
"test": "cool test"
}
}

Now you can run the command by running:

npm run build

Pro Tip: If your command requires config arguments that start with double dashes, you need to specify it twice when running via npm script. So if you want to run cool build --watch You need to run: npm run build -- --watch (with two sets of dashes). Otherwise, the command will not be recognized.

Run with npm bin

However, there are scripts that you want to run only occasionally, and it does not make sense to create a script for each one of them. In this case, you can run it directly by specifying:

node_modules/.bin/cool rare-command.

A shorter and friendlier way to do it is to use the npm and yarn bin command that returns the path to the executable path, and you can run:

$(npm bin)/cool rare-command

Have a command that you use often, but you do not want to put it in a script? set an alias for it, such as:

alias cl=$(npm bin)/cool

This command runs the cool script that is local to the project you run it.

Use NPX for Local Scripts

Starting NPM 5.2, NPM has a new package called NPX. NPX is extremely powerful, and too often, its powers are overlooked.
Use NPX to run local scripts: By merely typing npx cool inside a folder where cool-package is installed, NPX finds the local installation and run the script. If you need to pass any arguments, just send them, without any changes.

Use NPX for uninstalled Packages

When starting a new project using a CLI, such as Angular CLI, React Create App, or Vue CLI, the project does not yet exist. Therefore, you cannot install the generator package inside the project.

NPX is a lifesaver here, as you can run:

npx create-react-app my-app

NPX downloads the package to a temp folder and executes the command from there.

In the create-react-app, the name of the script is the same as the name of the package. If the package name is different from the command, you can specify the package name to be installed.

npx -package @angular/cli ng new my-app

Use Yarn

When installing Yarn, the bin command is automatically mapped to the yarn command, so you can run it as:

yarn cool

(Credit to @bnaya for this excellent comment!)

When To Use A Global Package?

After that said, there are cases where global packages are acceptable. The rule of thumb should be to use it when:

You run the commands mostly outside the context of specific projects.
You run the command relatively often, and you do not wait for NPX cache every time.
You are not extremely sensitive to the package's version, or versions do not change often.

For me, an example of such a package is http-server . I need it sometimes when I want to run a simple, well, HTTP server from a local folder for development and testing options. In this case, I would install the package globally.
Ah, and do not forget to update the version occasionally. Use npm outdated -g to see what packages need an update.

Conclusion

Run npm ls -g --depth=0 to see your currently installed global packages. Review them carefully, and always be conscious about the packages you install globally.

More often than not, you can avoid global packages and save yourself some precious debugging time.