DEV Community: Luca

Vue (2.x), Storybook (5.x), Web Components and nothing else

Luca — Sat, 03 Oct 2020 17:08:38 +0000

Intro
- What is Vue.js?
- What are Web Components?
- What is Storybook?
Definition of the problem
- Create a test project
- Add Storybook
- Create a web component
- Problem with styles
Hypothesis on the solution
Implementation of a solution
- vue_config.js
- Include the web component in the story
- Register the component
- Integrate the interface in the stories
Conclusions and credits

Intro

What is Vue.js?

Let's see what the docs say:

Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern tooling and supporting libraries.
[...]

In other words, Vue is a frameworks used to build frontend projects. It's pretty easy to use and the template code requested is minimal, it's however quite performant, indeed it was able to gain a respectable place near giants like React and Angular.

What are Web Components?

We've read a lot about web components in the last few years, and a lot we will read about it in the next future, so I will bring only a little synthesis: web components, in short, are none other than frontend components that, once registered by the browser and therefore recognized by it, can be used like normal tags with their attributes, parameters and peculiar behaviour.
They can be defined via js vanilla classes or a framework that supports them, specifically, as it's easly to guess, in this post we will talk about web components defined through Vue.js.

What is Storybook?

Storybook is an excellent tool useful when we have to test visually UI components, it's compatible with all major frameworks js and it can be used with js vanilla. All we have to do is to specify which component we have to render, to provide some mock data and let storybook instantiate our component in its own iframe and that's it. The criticality with vue arises from the difficulty of being able to instantiate simple web components without using other dependencies.

Definition of the problem

Create a test project

Create web components with Vue it's not a problem, there's a powerful cli that permit to specify an appropriate target for this task and, with some tricks, it's possible to test them even with the develop server.

Let's go now a little more in details, the procedure to define a web components with Vue is definitely trivial, let's start from a normal Vue project:

vue create vue-webcomponent-storybook-test

my configuration was typescript, babel, scss (dart-sass) e basic linter on save.
What we will obtain will be a tree like this:

├── dist
├── node_modules
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── assets
│   │   └── logo.png
│   ├── components
│   │   └── HelloWorld.vue
│   ├── App.vue
│   ├── main.ts
│   ├── shims-tsx.d.ts
│   └── shims-vue.d.ts
├── .gitignore
├── babel.config.js
├── package.json
├── README.md
├── tsconfig.json
├── vue.config.js
└── yarn.lock

If everything went smoothly, from the terminal, running yarn serve, we'll see our Vue app with the test component HelloWorld.vue make a fine show of its self on http://localhost:8080/.

Add Storybook

The next step is to install Storybook via the Vue plugin manager, also this operation like the last one it's not difficult at all:

vue add storybook

Storybook will add some files and folders:

├── config
│   └── storybook
│       └── storybook.js
├── dist
├── node_modules
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── assets
│   │   └── logo.png
│   ├── components
│   │   ├── Helloworld.vue
│   │   └── MyButton.vue
│   ├── stories
│   │   ├── index.stories.js
│   │   └── index.stories.mdx
│   ├── App.vue
│   ├── main.ts
│   ├── shims-tsx.d.ts
│   └── shims-vue.d.ts
├── .gitignore
├── babel.config.js
├── package.json
├── README.md
├── tsconfig.json
├── vue.config.js
└── yarn.lock

We can safely delete the component in src/components/MyButton.vue and the story in src/stories/index.stories.mdx, they will no longer needed for our project.

In the src/stories/index.stories.js file we create a story form the component App.vue:

Now, running the task storybook:serve, a test server will start and it will permit to run Storybook and testing our component:

npm run storybook:serve

(At the time of writing it seems that starting storybook with yarn is not possible).

Create a web component

Now we have to wrap our component (we will work with the default root component, App.vue, this will permit us to see how inclusion of others style's components works, however what we're talking about is replicable with any other component) in a class that extends HTMLElement. This operation will not be done by us, but through an api provided by Vue. At the end of this step the main.ts file will appear like this:

customElements.define(https://developer.mozilla.org/en-US/docs/Web/API/Window/customElements) is part of the js api that actually permit to register the component to the browser with the tag name my-web-component.
A little side note, if you're, like me, using typescript, you may need to add to the file shim-vue.d.ts the definition of the module @vue/web-component-wrapper:

declare module '@vue/web-component-wrapper';

In this way you'll avoid the error Could not find a declaration file for module '@vue/web-component-wrapper'. that on ide like IntelliJ and similar, may appear. it's odd that there isn't a d.ts pre-intalled that solve the problem.

At this point in the index.html of our project (in public/index.html) we've to get rid of the predefined root component (il div con id="app") and replace it with the newly registered one. Our index will therefore be:

Problem with styles

Running now the yarn serve command we're going to see our component work like a charm, right?

Well nope...

I mean yes, but actually no... where the hell are my styles????

The trouble is that Vue included the styles in the tag <head> of the page like always, but the component it's closed in a shadow dom (https://w3c.github.io/webcomponents/spec/shadow/), a sort of event horizon through which it's difficult (not impossible, something passes after all) to pass information.

And with Storybook instead? Well, things are that the problem remains. Modifying the index.stories.js like this:

And registering the component before using it (Storybook seem to not use how we include in the main.ts), it is possible render it, but styles are not present:

Hypothesis on the solution

A possible solution is described here, it seems that the option shadowMode of vue-loader is false by default, hence the strange behaviour previously seen. At this point set true that property may be solve the problem.

vue_config.js

All we have to do now is the vue_config.js in the root of the project, if not exists yet, we have to create it.

To know what to fill our file with it's necessary to inspect the webpack configuration of the project, with the command:

vue inspect

The results it seems to this:

If we look closely at this output, we can notice some interesting comments, for example:

/* config.module.rule('css').oneOf('vue').use('vue-style-loader') */

illustrating the api needed to generate that particular piece of configuration, this api, indeed, it's part of webpack-chain (https://github.com/neutrinojs/webpack-chain) tool used to facilitate the drafting of configuration files for webpack. Since it's already installed in the project, we can use for our purposes.

Obviously the parts of the configuration that interested us, are those where the property shadowMode: false appears, below the extract of the interested parts:

What we put in the vue_config.js will be intercepted from webpack anche integrated in the transpiling process, at the end, with the help of the documentation, we will obtain something like this:

this script add shadowMode:false everywhere is needed and permit webpack to proceed with the compilation process, finally we'll obtain a web component correctly rendered with its own styles incapsulated:

Include the web component in the story ()

if we run storybook now, we can see our component correctly rendered, however here the storybook api doesn't help us: how we can pass data to the component? What if these data are complex objects? How it's possible to interface with the component through the api exposed by the knob addon?

Ok let's proceed with order:

Register the component

This is easy, each component must be registered as we said before, one possibility is to implement a function that checks if the component is already registered and if not proceed accordingly, something like:

Really simple, elements that are not registered yet has HTMLElement() constructor, it's sufficient check it and that's it.

Subsequelty, the component must be registered:

Here too, nothing new, the procedure is the same seen before, only closed in a function.

Integrate the interface in the stories

Now we need to make sure we can use the addon-knobs to be able to pass data to our component and make it reactive to the changes that we can make during tests.
My solution was to build a function that returns a component and subsequentialy retrieves its reference to pass any data:

Let's try to understrand what this script actually do:

export const webComponentWrapper = ({props, template}) => {
...

In input an object is expected, for example:

props: {
  test: [
    ['test', true, 'GROUP-ID1'],
    boolean
  ],
},
template: '<test-component></test-component>'

formed by the property props which it will be another object, its element will have as keys the name of the property of the component and as value an array where the first element will be an array formed by:

property name (yes, too much redudancy),
value that will be considered
and the label that we want to assign to that specific knob.

The second value, instead, will be the function of the addon-knobs that will be used to process that specific data type (in this case boolean).

template is a string that rapresent the component and what it contains.

...
const id = generateRandomNumber(0, 10 ** 16);
...

Here generate a random id that will be pass to the component and used to retrieve its reference, I've create a specific function, but you can use a timestamp without any problem.

...
for (const key in props) {
  if (Object.hasOwnProperty.call(props, key)) {

    const old = key + 'Old' + id;
    const value = key + 'Value' + id;

    props[old] = null;
    props[value] = () => (props[old] !== null) ? props[old] : props[key][0][1];
  }
}
...

Now let's start working on the data to pass to the component: first of all we retrieve the property props and scroll through its contents, for each element, we decorate it with two others properties (the old and value variables), to the first we give null, to the second a function that will returns the old value (old) or the default one passed with the properties in props (be patient it's painful for me as it is for you), to understand the value true in ['test', true, 'GROUP-ID1'] that we talk about above, depending on weather the old value exists or not.

Every time, in Storybook, we select a specific component it will be reinitialized, in thi way, instead, we can pass each time the last value used in knobs, otherwise returning to a component previously visited we would lose the modifications made during tests and will see every time the first passed value.

return () => {
  setTimeout(() => {

    const root = document.getElementById(id.toString());
    const old = 'Old' + id;
    const value = 'Value' + id;

    for (const key in props) {

      if (Object.prototype.hasOwnProperty.call(props, key) && !key.includes(old) && !key.includes(value)) {

        const knobsParams = props[key][0];
        const knobsFunction = props[key][1];
        const tagElem = props[key][2];

        knobsParams[1] = props[key + value]();
        props[key + old] = props[key][1](...knobsParams);

        if (tagElem) {
          const elems = root.getElementsByTagName(tagElem)
          elems.forEach((item) => {
            item[key] = props[key + old];
          })
        }
        else {
          root[key] = props[key + old];
        }
      }
    }

  });

  return newTemplate;
}

The returned function is that will be executed by Storybook when a component is selected.

Before that function returns the template, a timeout without the time parameter is executed, so the handler will return in the event loop (cool video about event loop https://www.youtube.com/watch?v=8aGhZQkoFbQ&ab_channel=JSConf) as soon as possible, in this case just before the template become a element of the page.

The component reference, finally, is retrieved using the id previously calculated and the data extracted from the object passed to the main function are passed to the component. As said above, the data are saved in the propery added to props (here props[key + old] = props[key][1](...knobsParams);).

Conclusioni e credits

And that's all guys, putting everything together, you can have a Vue project ready to tests Web Components (not only vue normal classes) with Storybook and the included dev server. Here you can find a repository with a test project complete and working.

Thanks for reading this far.

Cheers

Fonti:

Vue (2.x), Storybook (5.x), Web Components e nient'altro

Luca — Mon, 28 Sep 2020 06:49:56 +0000

English version

Intro
- Cos'è Vue.js?
- Cosa sono i Web Components?
- Cos'è Storybook?
Definizione problema
- Creazione progetto di test
- Aggiunta di Storybook
- Creazione di un Web Component
- Problema con gli stili
Ipotesi sulla soluzione
implementazione di una soluzione
- vue_config.js
- Includere il web component nella story
- Registrare il componente
- Integrare l'interfaccia delle stories
Conclusioni e credits

Intro

Cos'è Vue.js?

Vediamo cosa dice la documentazione:

Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern tooling and supporting libraries.
[...]

In atre parole, Vue è framework javascript da utilizzarsi nella realizzazione di frontend. Dalla sua ha la semplicità d'uso e di setup, il template code richiesto è minimo ed è comunque performante, tanto da essere riuscito a ritagliarsi nel tempo un proprio rispettabilissimo spazio accanto a framework decisamente molto più noti ed utilizzati (sì ovviamente sto parlando di Angular e React). Niente di più, niente di meno.

Cosa sono i Web Components?

Se ne è scritto e tutt'ora se ne scrive (e spero se ne continuerà a scrivere) tantissimo, mi limiterò a fornire una piccola sintesi: i web components, in breve, non sono altro che componenti frontend i quali, una volta registrati dal browser e quindi da questo riconosciuti, possono essere usati come normali tag html con i propri attributi, parametri e comportamento peculiare.
Possono essere definiti tramite classi in js vanilla o usando un framework che li supporti, nello specifico, come è facile intuire, in questo articolo si parlerà di web component definiti utilizzando Vue.js

Cos'è Storybook?

Storybook è un eccellente tool per il testing visuale di componenti UI, compatibile con tutti i maggiori framework js ed utilizzabile anche con js vanilla. Tutto quello che si deve fare è specificare quale componente renderizzare, fornire dei mock data e lasciare che storybook istanzi il nostro componente in un proprio iframe e il gioco è fatto. La criticità con vue nasce dalla difficoltà di poter istanziare semplici web components senza utilizzare altre dipendenze.

Definizione del problema

Creazione progetto di test

Creare web components con Vue non è un problema, tanto che la sua cli permette di specificare un target apposito per questo compito e, con alcuni accorgimenti, è possibile testarli anche con il server di sviluppo.

Cerchiamo ora di andare un po' più nel dettaglio, la procedura per definire un web component in Vue è decisamente banale, partiamo da un normale progetto Vue:

vue create vue-webcomponent-storybook-test

la mia configurazione custom è stata typescript, babel, scss (dart-sass) e basic linter on save.
Ciò che si otterrà sarà un'alberatura di questo tipo:

├── dist
├── node_modules
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── assets
│   │   └── logo.png
│   ├── components
│   │   └── HelloWorld.vue
│   ├── App.vue
│   ├── main.ts
│   ├── shims-tsx.d.ts
│   └── shims-vue.d.ts
├── .gitignore
├── babel.config.js
├── package.json
├── README.md
├── tsconfig.json
├── vue.config.js
└── yarn.lock

Se tutto è andato liscio, da terminale, lanciando yarn serve, potremo vedere la nostra app con il componente HelloWorld.vue di test, fare bella mostra di se su http://localhost:8080/.

Aggiunta di Storybook

Il secondo passo consiste nell'installare Storybook attraverso il plugin manager di Vue, anche qui l'operazione non è particolarmente impegnativa:

vue add storybook

Storybook aggiungerà alcuni file e cartelle:

├── config
│   └── storybook
│       └── storybook.js
├── dist
├── node_modules
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── assets
│   │   └── logo.png
│   ├── components
│   │   ├── Helloworld.vue
│   │   └── MyButton.vue
│   ├── stories
│   │   ├── index.stories.js
│   │   └── index.stories.mdx
│   ├── App.vue
│   ├── main.ts
│   ├── shims-tsx.d.ts
│   └── shims-vue.d.ts
├── .gitignore
├── babel.config.js
├── package.json
├── README.md
├── tsconfig.json
├── vue.config.js
└── yarn.lock

Possiamo eliminare tranquillamente il componente src/components/MyButton.vue e la story src/stories/index.stories.mdx, non saranno necessari al nostro progetto.

All'interno di src/stories/index.stories.js creiamo una story per il nostro componente App.vue:

Ora lanciando il task storybook:serve, si avvierà un server di test che permetterà di eseguire storybook e testare il nostor componente:

npm run storybook:serve

(Al momento della scrittura sembra che avviare storybook con yarn non sia possibile).

Creazione di un Web Component

Il secondo passo consiste nel wrappare il nostro componente (lavoreremo con il componente root di default, App.vue, questo ci permetterà di vedere l'inclusione di altri componenti e come si comportano i loro stili, tutto è ovviamente replicabile per qualunque componente) all'interno di una classe che estende HTMLElement (link approfondimento), questo non verrà fatto direttamente da noi, ma attraverso una api fornita da Vue. Alla fine di questo step il file main.ts avrà questo aspetto:

customElements.define fa parte dell'api js che materialmente permette di registrare il nostro componente al browser con il tag name my-web-component.
Una piccola nota, se usate typescript come il sottoscritto, potreste dover aggiungere al file shim-vue.d.ts la definizione del modulo per @vue/web-component-wrapper:

declare module '@vue/web-component-wrapper';

Questo per evitare l'errore Could not find a declaration file for module '@vue/web-component-wrapper'. che su ide come IntelliJ e simili potrebbe essere apparso, strano non sia presente un d.ts già preinstallato che risolve il problema.

A questo punto nell'index.html del nostro progetto (in public/index.html) dovremo liberarci del root component predefinito (il div con id="app") e sostituirlo con il nostro componente appena registrato. Il nostro index, quindi, sarà:

Problema con gli stili

Lanciando ora il comando yarn serve vedremo in nostro componente funzionare alla grande, no?

Bhè no...

Cioè sì... ma in verità non proprio... dove diavolo sono finiti gli stili??

Il guaio è che Vue ha incluso gli stili nel tag <head> della pagina come farebbe normalmente, ma il nostro componente è rinchiuso dentro ad uno shadow dom (https://w3c.github.io/webcomponents/spec/shadow/), una sorta di orizzonte degli eventi attraverso cui è difficile (non impossibile, qualcosa passa tutto sommato) far passare informazione.

Con Storybook invece? bhe le cose non migliorano di molto, anzi il problema si ripropone. Modificando il nostro index.stories.js

Registrando il componente prima di utilizzarlo (storybook attualmente sembra non utilizzare quanto definito nel main.ts), è possibile renderizzarlo, ma non sono applicati gli stili:

Ipotesi sulla soluzione

Una possibile soluzione è descritta qui, a quanto pare l'opzione shodowMode di vue-loader è settata a false di default, da qui il cursioso comportamente riscontrato. A questo punto mettere a true quella proprietà dovrebbe risolvere il problema.

vue_config.js

Tutto ciò di cui abbiamo bisogno ora è il file vue.config.js nella root del nostro progetto; se ancora non esiste, creiamolo.

Per sapere con cosa riempire il nostro file è necessario ispezionare la configurazione webpack del nostro progetto con il comando:

vue inspect

Il risultato assomiglierà a questo:

Se guardiamo attentamente questo output, possiamo notare alcuni commenti interessanti, per esempio:

/* config.module.rule('css').oneOf('vue').use('vue-style-loader') */

che illustrano l'api necessaria a generare quel determinato pezzetto di configurazione, questa api, infatti, è parte di webpack-chain (https://github.com/neutrinojs/webpack-chain) tool utilizzato per facilitare la stesura di file di configurazione per webpack. Visto che è già installato nel nostro progetto, lo possiamo usare a nostro favore.

Ovviamente le parti della configurazione che interessano a noi sono quelle in cui appare la proprietà shadowmode: false, qui sotto l'estratto delle parti interessate:

Ora, ciò che mettiamo nel vue_config.js verrà intercettato da webpack e integrato nel processo di compilazione, e alla fine dovrebbe essere una cosa di questo genere:

questo script aggiunge shadowMode=falseovunque sia necessario e permette a webpack di procedere con la compilazione, finalmente quello che si avrà sarà un web component correttamente renderizzato che incapsula tutti i suoi stili:

Includere il web component nella story ()

Se lanciamo storybook ora, vedremo che anche lì il nostro componente sarà corretamente renderizzato, tuttavia l'api di storybook in questo caso non ci aiuta: come facciamo a passare dati al nostro componente in modo efficiente? Se questi dati sono oggetti complessi? Come si può interfacciare il nostro web component con l'api esposta dall'addon knobs?

Ok andiamo con ordine:

Registrare il componente

Questa è facile, ogni componente deve essere registrato come abbbiamo detto, un a possibilità è implementare una funzione che controlli se già il componetne non sia stato registrato e in caso contrario proceda di conseguenza, qualcosa del genere:

Davvero molto semplice, gli elementi non registrati hanno come constructor HTMLElement(), è sufficente fare un check e il gioco è fatto.

Successivamente, il componente va registrato:

anche qui nulla di nuovo, la procedura è quella vista poco sopra, soltanto chiusa dentro una funzione.

Integrare l'interfaccia delle stories

Ora dobbiamo fare in modo di poter usare l'addon-knobs per poter passare dati al nostro componente e renderli reattivi ai cambiamenti che possiamo fare durante i test, la mia soluzione è stata costruire una funzione che restituisse un componente e succesivamente ne recuperasse il riferimento per potergli passare eventuali dati:

Cerchiamo di capire cosa questo script effettivamente fa:

export const webComponentWrapper = ({props, template}) => {
...

In ingresso ci si aspetta un oggetto, per esempio:

props: {
  test: [
    ['test', true, 'GROUP-ID1'],
    boolean
  ],
},
template: '<test-component></test-component>'

formato dalla proprietà props che sarà un altro oggetto, i suoi elementi avranno come chiave il nome della proprietà del nostro componente e per valore un array dove il primo elemento sarà un ulteriore array formato da

nome proprietà (sì c'è un po' di ridondanza di cui è possibile liberarsi),
valore che si dovrà considerare
e l'etichetta che vogliamo dare al gruppo di dati di quello specifico knob.

Il secondo valore, invece, la funzione dell'addon knobs che verrà utilizzata per trattare quello specifico tipo di dato (in questo caso boolean).
template invece è una stringa che rappresenta il nostro componente e quello che contiene.

...
const id = generateRandomNumber(0, 10 ** 16);
...

Qui generiamo un id casuale che verrà utilizzato poi per applicarlo al componente e recuperarne il riferimento, io ho creato una funzione apposta, ma in effetti può essere benissimo un timestamp qualunque.

...
for (const key in props) {
  if (Object.hasOwnProperty.call(props, key)) {

    const old = key + 'Old' + id;
    const value = key + 'Value' + id;

    props[old] = null;
    props[value] = () => (props[old] !== null) ? props[old] : props[key][0][1];
  }
}
...

Ora cominciamo a lavorare sui dati da passare al componente: prima di tutto prendiamo la proprietà props e ne scorriamo il contenuto, per ogni elemento preso in considerazione, lo arricchiamo di altre due proprietà (le variabili old e value), alla prima diamo null alla seconda una funzione che ritornerà il vecchio valore (old) o quello di 'default' passato assieme alle proprietà (per capirci, il valore true nel ['test', true, 'GROUP-ID1'] di cui abbiamo parlato più su) a seconda che il vecchio valore esista o meno.

Ogni volta che in Storybook selezioniamo un certo componente questo viene reinizializzato, con questo sistema riusciamo a passare sempre l'ultimo valore usato nei knobs, diversamente ritornando su un componente perderemmo le modifiche fatte durante i nostri test e vedremmo sempre il primo valore passato.

return () => {
  setTimeout(() => {

    const root = document.getElementById(id.toString());
    const old = 'Old' + id;
    const value = 'Value' + id;

    for (const key in props) {

      if (Object.prototype.hasOwnProperty.call(props, key) && !key.includes(old) && !key.includes(value)) {

        const knobsParams = props[key][0];
        const knobsFunction = props[key][1];
        const tagElem = props[key][2];

        knobsParams[1] = props[key + value]();
        props[key + old] = props[key][1](...knobsParams);

        if (tagElem) {
          const elems = root.getElementsByTagName(tagElem)
          elems.forEach((item) => {
            item[key] = props[key + old];
          })
        }
        else {
          root[key] = props[key + old];
        }
      }
    }

  });

  return newTemplate;
}

la funzione ritornata è quella che verrà eseguita da Storybook ogni volta che si selezionerà quel determinato componente.

Prima che questa ritorni il template (nulla più che una stringa del tipo <my-web-component></my-web-component>), si esegue un timeout privo dei milliscondi di durata, questo permette all'handler di rientare nella coda del loop event appena sarà possibile (più informazioni qui), in questo caso appena il template diventa un elemento della pagina.

Viene recuperato il riferimento del componente tramite l'id calcolato prima, dopo di che vengono recuperati i dati dall'oggetto passato alla funzione e passati al componente. Come detto prima, il dato viene salvato nella proprietà aggiunta prima (qui props[key + old] = props[key][1](...knobsParams);).

Conclusioni e credits

E questo è quanto, mettendo tutto assieme, si riesce ad avere un progetto Vue per testare web components (e non solo normali classi Vue) con Storybook e il dev server incluso. Qui trovate un repository con un progetto di test completo e funzionante.

Fonti: