<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Alberto De Agostini on Medium]]></title>
        <description><![CDATA[Stories by Alberto De Agostini on Medium]]></description>
        <link>https://medium.com/@alberto.deagostini-thron?source=rss-435ed59db25f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*wlZcSbXecDLFBgPrlaPiaQ.jpeg</url>
            <title>Stories by Alberto De Agostini on Medium</title>
            <link>https://medium.com/@alberto.deagostini-thron?source=rss-435ed59db25f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 16:24:45 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@alberto.deagostini-thron/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Web Workers to improve UI performance]]></title>
            <link>https://medium.com/thron-tech/web-workers-to-improve-ui-performance-a409a0714d92?source=rss-435ed59db25f------2</link>
            <guid isPermaLink="false">https://medium.com/p/a409a0714d92</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[javascript-tips]]></category>
            <category><![CDATA[performance]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Alberto De Agostini]]></dc:creator>
            <pubDate>Thu, 12 Nov 2020 07:32:23 GMT</pubDate>
            <atom:updated>2020-11-12T07:32:23.491Z</atom:updated>
            <content:encoded><![CDATA[<h4>Why you should always consider Javascript Workers in your project</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xBwTQI9R0y-gwXqR0PRp6w.png" /></figure><p>Javascript workers have been introduced around 2010 and are interesting because they address one of the biggest shortcomings of javascript: being single-threaded.<br>With time, different types of workers are being introduced to the language with different objectives, here is a quick summary of them.</p><p><strong>Web workers</strong> are the first added workers and are the most general-purpose type. Unlike service workers and worklets as we will see below, they do not have a specific use case, other than the feature of being run separately from the main thread. <br>As a result, web workers can be used to offload pretty much any heavy processing from the main thread, gaining some performance in the main thread, the one where the UI is running.<br>You should consider whether to use them if you have heavy tasks that don’t need interaction with the UI.<br><a href="https://johnresig.com/about/">John Resig</a> has an amazing <a href="https://johnresig.com/blog/web-workers/">post of real-world use cases of web workers</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6eiUL94hXdWxkuK-JZPr7Q.png" /><figcaption>Web Worker browser support (from caniuse.com)</figcaption></figure><p><strong>Shared Workers</strong> are a special worker that can be accessed by any script that comes from the same domain. Web workers can be accessed only from the script that created them.<br>This means that if you have multiple applications hosted under the same domain, you could send and receive a message between these applications using the shared workers. This means that you could build a worker that caches information, any app that invokes an API could save the result in the shared worker and could ask the worker if the information is already there to avoid doing the same request between different applications. These workers are actually rarely used (at least I’ve not seen a lot of them) and are not widely supported (<a href="https://github.com/whatwg/html/issues/315">there was also an issue to remove them</a>)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wjhJpM1r_k_B6E2ST9bIDQ.png" /><figcaption>Shared Worker browser support (from caniuse.com)</figcaption></figure><p><strong>Service workers</strong> are a type of worker that serve the explicit purpose of being a proxy between the browser and the network. This means that they can cache resources, modify the outgoing request, or modify the response received from the server.<br>They are probably the most powerful API that has been added to the web platform recently. <br>They gained a lot of attention with the PWA’s and they let you achieve functionality that you couldn’t before like:<br>- Receival of push notification<br>- Apps working in offline mode<br>- and more…<br>You should consider them if you want your web app to work similarly to a mobile app or you want to handle push notifications, work offline, etc… You can find everything they enable you to do <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API">here</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*okYJc1gEIquaCvbTgBsqyw.png" /><figcaption>Service Worker browser support (from caniuse.com)</figcaption></figure><p><strong>Worklets</strong> are a very lightweight, highly specific, worker. They enable us, as developers, to hook into various parts of the browser’s rendering process.<br>So basically they are hooks into the browser’s rendering pipeline, enabling us to have low-level access to the browser’s rendering processes such as styling and layout.<br>You can think of them as lightweight, low-level Web Worker, they are still in an <a href="https://developer.mozilla.org/en-US/docs/Web/API/Worklet">experimental-ish state</a> so I would not use them in production. They might be interesting in the future</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bMZ0u3cq-KJ-1KNbnRItjQ.png" /><figcaption>Worklet browser support (from caniuse.com)</figcaption></figure><h4>Which worker we use and how</h4><p>Our product must support Internet Explorer 11 (at least <a href="https://death-to-ie11.com/">for now</a>). This requirement puts strong constraints and cuts off pretty much every choice except for the “simple” one, the Web Worker.<br>We began adopting workers in early 2018. Around that time we started to split our monolithic web application (<a href="https://medium.com/thron-tech/single-page-application-from-monolithic-to-modular-c1d413c10292">article</a>) and we thought that one of the libraries (we call it ThronModels) that we were developing would have been a nice use case for workers because it is responsible to make the HTTP request to our backend APIs, model the result and return it. This means that it has no connection to the DOM and it just does <em>logical</em> operations, it is not linked with anything that is related to the UI (because web workers live in a separate thread they have no access to the DOM).</p><p>Even if we were sure that lifting some work from the main thread was a nice idea we weren’t 100% confident that this would have had no drawbacks, so we added a fallback to make the library work even without Workers. The cost for doing so was small and we thought that was a nice idea to implement the fallback and then removing it if it proved to be not useful later on.<br>This turned out to be a great idea because it came in pretty handy in the long run. We will talk about the troubles that the workers caused in a moment. Let’s find out the goodies first.</p><p>Recently we developed a web application that is an interactive version of the documentation of some APIs (something similar to <a href="https://petstore.swagger.io/">this</a>). <br>The app must fetch an <a href="https://github.com/OAI/OpenAPI-Specification">OpenApi</a> JSON file, parse it, and then build the interface accordingly. This specification can grow a lot over time so we thought that fetching and parsing this <em>possibly big</em> file was another perfect use case for the workers, so we did it.<br>This time we changed approach and we opted for <a href="https://webpack.js.org/loaders/worker-loader/">webpack worker loader</a>, this webpack plugin lets you write a “normal” javascript file (it must have an `onmessage` function because if it doesn’t, you won’t be able to communicate with the worker) that is compiled and handled as a worker automatically… Like most of the webpack plugins, it’s <strong>Magic</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/220/1*nwBe22SehHzJJQ-86R1LIw.gif" /><figcaption>webpack is magic</figcaption></figure><p>We added a layer of abstraction to avoid having to deal with `onmessage` and `postMessage` of the worker and everything worked nicely and easily. <br>We also used babel worker to let us use all the latest js functionality inside the worker file</p><p>The result was better than expected. With low-end devices, you can see the difference in the reactivity of the page while it is loading.<br>If you have some task that is pretty heavy, try to use a Worker, the benefit can be huge. Have a look at these codepens to see with your eyes the difference that they can make:</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fcodepen.io%2Falbertodeago%2Fembed%2Fpreview%2FjOrVaQr%3Fheight%3D600%26slug-hash%3DjOrVaQr%26default-tabs%3Djs%2Cresult%26host%3Dhttps%3A%2F%2Fcodepen.io&amp;display_name=CodePen&amp;url=https%3A%2F%2Fcodepen.io%2Falbertodeago%2Ffull%2FjOrVaQr&amp;image=https%3A%2F%2Fassets.codepen.io%2F3923308%2Finternal%2Fscreenshots%2Fpens%2FjOrVaQr.default.png%3Ffit%3Dcover%26amp%3Bformat%3Dauto%26amp%3Bha%3Dtrue%26amp%3Bheight%3D360%26amp%3Bquality%3D75%26amp%3Bv%3D2%26amp%3Bversion%3D1603369876%26amp%3Bwidth%3D640&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=codepen" width="800" height="600" frameborder="0" scrolling="no"><a href="https://medium.com/media/b4af9a8c90d2ce584ce2c9eed0ec32f6/href">https://medium.com/media/b4af9a8c90d2ce584ce2c9eed0ec32f6/href</a></iframe><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fcodepen.io%2Fjgerigmeyer%2Fembed%2Fpreview%2FvKixI%3Fheight%3D600%26slug-hash%3DvKixI%26default-tabs%3Djs%2Cresult%26host%3Dhttps%3A%2F%2Fcodepen.io&amp;display_name=CodePen&amp;url=https%3A%2F%2Fcodepen.io%2Fjgerigmeyer%2Fpen%2FvKixI&amp;image=https%3A%2F%2Fassets.codepen.io%2F79220%2Finternal%2Fscreenshots%2Fpens%2FvKixI.default.png%3Ffit%3Dcover%26amp%3Bformat%3Dauto%26amp%3Bha%3Dtrue%26amp%3Bheight%3D360%26amp%3Bquality%3D75%26amp%3Bv%3D2%26amp%3Bversion%3D1410962236%26amp%3Bwidth%3D640&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=codepen" width="800" height="600" frameborder="0" scrolling="no"><a href="https://medium.com/media/460f685c6879bf2cc52141caae1e5de2/href">https://medium.com/media/460f685c6879bf2cc52141caae1e5de2/href</a></iframe><h4>Do the workers have downsides?</h4><p>The worker adoption brought some issues that we did not anticipate:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TBMNxrvrUkzZp4bs6bqy4A.png" /></figure><p><strong>Mocking requests</strong><br>- We found an issue with workers and testcafè: HTTP requests that are started from the worker won’t be intercepted by the framework and this leads to the impossibility of testing the worker.<br>To bypass this issue we found 2 possible solutions:</p><p>1. When opening the page to test, simply “remove” the worker from the window to prevent the library to use it:<br>“window.Worker = undefined;”<br>By doing this the ThronModels library will detect that the Worker API is not there and thus it will fallback to run the same exact code but in the UI thread. This way testcafé can intercept and mock all the requests we want.</p><p>2. Add some sort of flag on the page while testing and avoid using the Worker if that flag is true<br>“window.__disableWorker__ = true;”<br>Then check that flag in ThronModels library to “choose” if we need to use a worker or not.</p><p>We used the first solution but the second one is also easy to implement. None of the solutions are elegant, but they work just fine for our cases.</p><p><strong>Workers need a javascript file</strong> <br>The Worker needs a file to work: when you create a new worker it requires the URL of a script as an input parameter. This can be annoying, especially if you are developing a library like the one I used as an example above.<br>That javascript library is hosted in NPM and thus, we needed no CDN at all, the web applications that need to use the library would just install it from NPM.<br>But our library creates a worker and it expects to receive an URL of a javascript file to import, luckily we already have hosting and CDN setup so this was not an issue for us (we also needed hosting for the <a href="https://medium.com/thron-tech/choosing-between-vuepress-storybook-and-vuestyleguidist-102ef7fa6382">documentation we write with Vuepress</a>) but keep this in mind.<br>I’m sure there might be some tool to mitigate this issue but it’s something you should pay attention to (check out <a href="https://github.com/GoogleChromeLabs/comlink">comlink</a> by Google and the amazing <a href="https://github.com/surma">Surma</a>, or <a href="https://github.com/developit/greenlet">greenlet</a> by <a href="https://github.com/developit">Jason Miller</a> — as amazing as Surma :D)<br>Because of this, we have to remember on every deploy, not only to publish the new library version in npm, but also to deploy this static asset for the worker, but this is easily mitigated if you have a CI/CD where you can add a task to automate it.<br>We still don’t have a CD setup yet (it’s in progress) so we are doing it manually (triggering a Jenkins job) at every deployment. The fallback we implemented proved to be helpful in those cases where operators did forget about deploying the worker file.</p><p><strong>Requests are the same but different</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/589/1*EurT_ANQmR7mAoQi-nwGsg.gif" /><figcaption>Requests are not 100% the same</figcaption></figure><p>I said that we use the Worker to make HTTP requests in a library.<br>When we started working on a new project, some time ago, we had some issues while integrating on a specific API. This API had a validation on the referer header and we realized (after some debug headache) that the requests sent from the Worker did not include this header. We tried and searched on the web if this limit was avoidable but actually found pretty much zero information about that. So in that specific project, we turned off the Worker (the fallback again was useful).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*y7HE8Vc5a2VgsmCijJk93g.png" /></figure><p>A limitation to emphasize is that you cannot manipulate the DOM inside the worker (because they run in an isolated and separated thread compared to the UI) so you can use them to make massive blocking operations but not to update the DOM or stuff like that. This is because when you send a message to the worker using the <em>postMessage</em> the browser can serialize the message into a JSON string, it can construct a clone of the message (to allow more complex data to be sent, more info <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">here</a>) or it can transfer the ownership of the message to the worker.<br>All of this is done to avoid sharing memory between the threads and because javascript was originally designed to be single-threaded.</p><h3>Conclusion</h3><p>Web workers can bring massive improvements in UI responsiveness, especially if you have synchronous blocking operations.<br>However, you have to be prepared to have some unexpected issues if you don’t study before using them: we didn’t found any evidence of the fact that the worker does not send the referer header so we probably would never have caught that problem before facing it. If you know something about it please leave us a comment.<br>If you can rely on better browser support, other workers could help you improve your app even more, so pay double attention to your minimum browser version to be supported when starting a new project (especially the Service Worker)</p><p>We plan to continue using javascript workers and evaluate if it is appropriate to move pieces of code in the workers to lighten the UI even further as we add features or start new projects.</p><p>Do you also use webworkers? Have you encountered any other unexpected behaviors? If so, how did you overcome them?</p><h3>Bonus</h3><p>There is a framework that is experimenting with the full use of Workers, check out <a href="https://github.com/neomjs/neo">neomjs</a>, it’s very promising<br>If you find this topic interesting, I advise to read <a href="https://surma.dev/things/when-workers/">Surma’s article</a> about workers, it further explains details and it includes more benchmarks and examples</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a409a0714d92" width="1" height="1" alt=""><hr><p><a href="https://medium.com/thron-tech/web-workers-to-improve-ui-performance-a409a0714d92">Web Workers to improve UI performance</a> was originally published in <a href="https://medium.com/thron-tech">THRON tech blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Choosing Between Vuepress, Storybook, and Vuestyleguidist]]></title>
            <link>https://medium.com/thron-tech/choosing-between-vuepress-storybook-and-vuestyleguidist-102ef7fa6382?source=rss-435ed59db25f------2</link>
            <guid isPermaLink="false">https://medium.com/p/102ef7fa6382</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[vuejs]]></category>
            <category><![CDATA[automation]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Alberto De Agostini]]></dc:creator>
            <pubDate>Wed, 15 Apr 2020 07:31:01 GMT</pubDate>
            <atom:updated>2020-04-15T07:31:01.022Z</atom:updated>
            <content:encoded><![CDATA[<h4>A comparison of the 3 most used, modern UI documentation tools in the Vue ecosystem</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qC69lkiZl3kmFNM-vSXclg.png" /></figure><h3>Why are we doing this</h3><p>Internal documentation is often a challenge for engineering teams, we all know that excellent documentation is an investment, but at the same time it is very expensive to write, incredibly hard to maintain and it clashes with the speed of development that is required in a fast-moving, agile company. In this fast-pacing environment, some might even argue that by the time you write and curate the documentation you have to refactor everything, thus voiding the documentation itself.</p><p>In the past, we reached a point where documentation in frontend projects was pretty much absent. People come and people go and with time, parts of the codebase became legacy because no one knew how they behave and, worse, how they should behave. <br>This can lead to frustration, a lot of spent time on some bug fixing that would have been trivial with documentation and also to longer onboarding times for newcomers.</p><blockquote>Legacy code: the code that no one wants to maintain</blockquote><p>We have reached a point of (more) stability and the needs of easing the onboarding of new developers and to create a solid and comprehensive test suite are pushing us to improve our current documentation for the frontend components (mainly js) development</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zhXMXGNyY2PwMf1yRHTn4w.jpeg" /></figure><h3>Our requirements</h3><p>We need documentation for different libraries, often with different scopes. One library might be responsible for HTTP requests, another one is a js helper, another one is a component library… and so on.<br>We have no strict requirements, we just want our documentation to be pretty, efficient (the required information must be available easily, thus a search would be great) and not too hard to maintain, automatic tools would be great.<br>One plus for component library documentation is to have the possibility to create interactive examples (quickly test the result on the doc page) to let the user feel and use the components immediately.</p><h3>What we’ve done so far</h3><p>As we said, we have now multiple “common libraries” and especially for these common ones, the need for good docs is huge.<br>For this objective, we’ve separated the libraries in two groups, one for libraries that have UI and one for the remaining ones: a library doing HTTP requests is in the latter group.<br>We think having consistency across docs is great, but efficiency and maintainability are better, so we are not forcing ourselves to choose only one tool.</p><p>We first explored tools for the non-UI libraries. There are many tools for this kind of purpose, but we immediately choose one because we already had experience with it and it worked like a charm.<br><a href="https://documentation.js.org/">Documentation.js</a><br>This is a great tool because it automatically parses jsdoc and creates markdown or HTML files from it. The default output is not the best looking one but it gets the job done.</p><p>For the libraries that expose UI components, we evaluated some tools based on our tech stack. Since we use Vue, we focused on these three libraries that compete for being the best one: <a href="https://storybook.js.org/">Storybook</a>, <a href="https://vue-styleguidist.github.io/">Vue Styleguidist</a>, and <a href="https://vuepress.vuejs.org/">VuePress</a>. <br>This is the summary of our decision outcome:</p><h4>STORYBOOK</h4><p>As its website states:</p><blockquote>Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient.</blockquote><p>It’s getting more and more attention from the community and it deserves it. It’s a great tool able to solve (probably) all the use cases.</p><p>PROS</p><ul><li><strong>interactive</strong>: by default, it lets the user “play” with components. This is a huge plus because not only the user/developer can read the component APIs but it lets them also see the component, change the properties and experience the immediate effect.</li><li><strong>super extensive</strong>: it offers a huge amount of plugins and some of them are amazing, like <a href="https://storybook.js.org/docs/testing/structural-testing/"><em>storyshot</em></a> to run test suites for the components inside the documentation itself.</li></ul><p>CONS:</p><ul><li><strong>not the prettiest by default</strong>: there is some work needed to make it “pretty looking” (there are themes but still, work to do).</li><li><strong>time-consuming</strong>: more time expensive compared to the other two tools to have the first full documentation up and running</li></ul><h4>VUESTYLEGUIDIST</h4><p>This is another tool specific to create component documentation. This time for Vue components (it was born as a fork from <a href="https://react-styleguidist.js.org/"><em>react styleguidist</em></a> so if you are a react user you might have that one).<br>It generates documentation based on the comments (an extension of jsdoc language) in your source code declarations and markdown files.</p><p>PROS:</p><ul><li><strong>automatic</strong>: it generates automatic docs by parsing jsdoc-like comment. Due to this, it’s the tool to pick if you want to get a nice documentation in the minimum amount of time, because you are going to just need a good documentation inside the definitions of the components.</li><li><strong>Vue ecosystem</strong>: not one of the most known Vue official libraries, but it’s one of them, so probably a good support is expected over time.</li></ul><p>CONS:</p><ul><li><strong>flexibility</strong>: it does a lot of things automatically, this is a good thing but also a bad one, it looks very hard to do something custom and we fear that over time this can be an issue for us.</li><li><strong>a bit buggy</strong>: using it we found some bugs, the maintainer support was great, but still, not perfect.</li><li><strong>limited</strong>: we had a hard time documenting directives (there is not an official way to do it) and mixins, so you still end up writing different parts yourself.</li></ul><h4>VUEPRESS</h4><blockquote>Vue-powered Static Site Generator</blockquote><p>This one is not a documentation tool, it’s just a static site generator.<br>It’s created by Evan You (Vue.js creator) and its main goal is to be simple and performant, creating a website given markdown and Vue files.</p><p>PROS:</p><ul><li><strong>official</strong>: this is the tool used by the majority of open source libraries to write their documentation. Needless to say, it works well and it offers huge community support.</li><li><strong>pretty</strong>: by default, it looks pretty. Also, it’s easy to do minor customization.</li><li><strong>versatile</strong>: it parses MD files but inside them, you can also write HTML and Vue, so if you install your library as a plugin in a Vuepress’ Vue instance, you can use your components in the docs (other tools has similar capability too).</li></ul><p>CONS:</p><ul><li><strong>not automatic</strong>: you have to write documentation in MD files, there is no jsdoc parsing or such things. Good thing is that you can use also HTML and Vue inside this markdowns;</li><li><strong>Server Side Rendered</strong>: to install and use your library in the documentation (for example to create interactive examples) it must be SSR friendly because Vuepress compiles everything into a static site, thus in a node.js environment.</li></ul><h3>Choice</h3><p>We believe that Storybook is the most complete tool out there, but it is also the one that requires the largest amount of time to make the documentation reach a production-ready state.<br>VueStyleguidist is a very nice tool, great for most of the use cases but probably for some enterprises, it’s still not perfect yet.<br>In the end, we decided that <strong>Vuepress</strong> is the <em>best choice for our needs</em>, it stands as a mid-tier between the other two tools. It is just a static site with no automatic magic behind it, but its simplicity makes it very easy to customize in the future.</p><h3>Cool parts</h3><p>Do you remember that we said that we were not limiting us to just one tool because we wanted the best one for the different cases? We also said that it would be cool to have a common look and feel for all the documentation, it would provide a more uniform user experience.<br>We chose Documentation.js for the non-UI libraries and Vuepress for the UI ones, needless to say, these two tools don’t give similar outputs for the end-users.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2_OBu-wyWDH4QCOX7nyPsg.jpeg" /><figcaption>Difference between documentation.js (above) and Vuepress (below)</figcaption></figure><p>Let’s see if there is something we can do about this.<br>We can try to style both outputs similarly. Like creating a theme for Vuepress and one for documentation.js or just create a documentation.js theme similar to the default one of Vuepress (because the latter is pretty already).<br>Documentation.js is not limited to exporting the result in HTML format only, it also gives you the option to get the output in markdown format. Vuepress takes markdown as input to create a static site… Do you see where I’m going?<br>The two tools match perfectly. We created a node script that launches the documenation.js creating the markdown and then builds the Vuepress static site starting from that source. This way we have a consistent style for libraries regardless of which tools we are using.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oxH5AVjxX5OTT8CbEzMG4w.jpeg" /><figcaption>Output of a documentation of a non-UI library (above) and a UI one (below)</figcaption></figure><p>For the UI libraries, the documentation is still manual, but we also think that that type of documentation is “less boring” to create and the interactive examples are still going to be created on a case-by-case basis, so we think is an acceptable compromise.</p><h3>Not so cool parts</h3><p>For the UI component library, we wanted to create interactive examples to improve the user experience. We were not able to just install our library as a Vue plugin in the Vuepress’ Vue instance because our library is not SSR (Server Side Render) ready. This made us lose a bit of time by searching what we could do about it. <br>The best choice would be to modify the library to be SSR ready but this would be too much effort, we might plan to do it in the future.<br>Here’s what we did instead:</p><p>We create a small HTML page for each example we want to show, we put it in the .vuepress/public folder, so they are served automatically with the documentation. Then in the Vuepress markdown, we create an iframe (you can write HTML there) that points to the right example. <br>It might be not the most elegant solution but it works well enough and it also separates examples from the docs itself, so you don’t end up with a mix of the two (of course if the library was installed as a plugin you could achieve the same cleanliness by separating examples with ad-hoc components).<br>To make the dev life easier and to simplify the maintenance of the documentation for new-comers we created an HTML template for these examples that automatically installs everything’s necessary, we just have to fill 3 placeholders, one for style, one for template and one for the script.<br>The biggest downside of this approach, in my opinion, is that the iframes are slow and when you load the documentation you see the example popping out after all the other content. Probably not the greatest issue but it’s still not a pleasant experience for the end-user.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/890/1*xZAVlxCWq-9v1F_m3DBWsg.gif" /><figcaption>Example “appearing” at page load due to iframe being loaded after page render</figcaption></figure><p>We could not easily change the way the page is loaded and rendered, for this reason, we leveraged the end-user perception: we added a fade-in animation to the examples (the fade logic is built-in in the template just mentioned so there is nothing to do, it is being generated automatically for every example, ensuring future ones will have it too)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/890/1*ahIZNK3Q6QvHDB0DCxNqlw.gif" /><figcaption>Example loading with a fade animation on page load, end-user perception is much better</figcaption></figure><p>This whole iframe solution is working well enough. <br>This is the code for the example template:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HVsH5Rrc-QewCf_qvdGayw.png" /><figcaption>HTML template for examples</figcaption></figure><p>And this is the script we import, that handles plugin installation and the fade animation:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0aG9bIR3N5lbyLF5qs3awg.png" /><figcaption>javascript file imported by example to add fade</figcaption></figure><h3>OUTCOME</h3><p>We are very happy with the results, using the same tech for all the libraries gives a consistent style improving the end-user experience.<br>We are using this solution to manage all our frontend documentation and we are very happy about the efficiency, the automation and the quality of output we have been able to achieve. All our new libraries follow this standard now.</p><p>What do you think about this? Would you have taken a different approach? We’re happy to hear your opinion, don’t hesitate to contact us or to write in the comment section below.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=102ef7fa6382" width="1" height="1" alt=""><hr><p><a href="https://medium.com/thron-tech/choosing-between-vuepress-storybook-and-vuestyleguidist-102ef7fa6382">Choosing Between Vuepress, Storybook, and Vuestyleguidist</a> was originally published in <a href="https://medium.com/thron-tech">THRON tech blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[“Buy or make” dilemma can be hard in frontend development: the 360 Product View case]]></title>
            <link>https://medium.com/thron-tech/buy-or-make-dilemma-can-be-hard-in-frontend-development-the-360-product-view-case-4813448410dd?source=rss-435ed59db25f------2</link>
            <guid isPermaLink="false">https://medium.com/p/4813448410dd</guid>
            <category><![CDATA[html5]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[frontend-development]]></category>
            <category><![CDATA[canvas]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Alberto De Agostini]]></dc:creator>
            <pubDate>Thu, 08 Nov 2018 14:51:38 GMT</pubDate>
            <atom:updated>2018-11-09T14:56:39.637Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<h4>We dived into the development of a very common frontend feature and realised we couldn’t use any of the available libraries. What went wrong and what went right in our experience.</h4><p>Modern users expect more and more from content and their experience interacting with it. Static images, while still being important, are not driving enough engagement to users and are surpassed by interactive experiences such as videos and multi-point-of view experiences.<br>One of the simple content-interactions users are used to have is the ability to see a product in detail from all angles while choosing whether to buy it or not (we call it 360 product view).</p><p>It’s a very common objective and we didn’t expect to build our own solution for this, there are many ready-to-use solutions but, in the end, we couldn’t find any suitable one.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/250/1*oFi2yzCjmTxJLKukBk6hiA.gif" /><figcaption>Example of 360 product view</figcaption></figure><p>Our product includes a web component (usually referred as “the player”) that is able to manage different content types (audio, video, pictures, documents, galleries, etc), it is modular and can be easily extended or personalized by any web developer with average Javascript knowledge.</p><p>Our goal was to integrate in our “player” the rendering a 360degree product view feature in a seamless way. There were some key requirements:</p><p>Mandatory:</p><ul><li>Compatible with Chrome, Firefox, Safari, Edge and IE9+. Yes, some companies still use that.</li><li>Compatible with mobile browsers (at least chrome and safari latest releases).</li><li>Personalisation has to be consistent player’s one: our player can be easily customized by providing CSS and JS modules through a dedicated area in our product, this has to propagate to the 360 product view too.</li></ul><p>Nice to have:</p><ul><li>zoom the content (at least or zoom or rotate something like <a href="http://spritespin.ginie.eu/samples/#/plugins-zoom">this</a>)</li><li>pan when content is zoomed (like <a href="https://www.ajax-zoom.com/">this</a>)</li></ul><p><strong>Buy or make?</strong></p><p>Our initial thought was: “hey, out there there has to be a library that perfectly fits our needs. We will pick it, adapt it and reach objective with low effort!”. <br>We then begun our search and found a lot of libraries / plugins that were handling product views, less than we thought but still a good amount.</p><figure><img alt="" src="https://cdn-images-1.medium.com/proxy/1*uWgIV-BCWP-fw8MzXLyuwA.jpeg" /></figure><p>Quickly enough we discarded the majority of those libraries for various reasons: some were just plain ugly, some were working ok but they felt “old” and the majority of them didn’t fullfil all the requirements (most were not allowing the zoom feature and I did want to have it in our Product View, because details matter when looking at a product you want to buy). <br>The remaining libraries were just:</p><ul><li><a href="https://www.ajax-zoom.com/">Ajax-zoom</a></li><li><a href="https://www.magictoolbox.com/magic360/">Magic360</a></li><li><a href="http://spritespin.ginie.eu/">Spritespin</a></li></ul><p>Some of those are not free (which is not an issue but if we pay for it, we expect quality from it) and all of them would have required us to perform tweaks to support our customization class hierarchy.<br>The first library we explored was Spritespin, it looked fine but it didn’t have zoom and rotate-while-zooming features out of the box, so we moved to Magic360. Magic360 was better but still missed the same features and it also has a commercial license only. The last one, Ajax-zoom, had everything we wanted and it looked pretty cool. Unfortunately there were 2 issues here:</p><ul><li>It requires backend functionality. This means that we need to plan for both frontend and backend integration, adding a new dependency on our player component on devops/backend compentences, causing increased complexity and maintenance costs in the future;</li><li>It only has a commercial license, adding license cost to the integration ones .</li></ul><p><strong>Try to make</strong></p><p>A quick estimate about the time required to deeply evaluate those libraries, include them in our player and extend it made us also consider the following option: “maybe we can take the best from these libraries and implement a bespoken solution, perfect for our needs and it would take about the same amount of time.”</p><p>So we created few proof of concepts with different techniques to understand how difficult it would be to implement such component and estimate the time it would take to fully implement it. <br>The first POC was to evaluate whether we should just append a lot of images and put a drag listener to show and hide the right ones or put just one image and change the source attribute through the drag listener.</p><p>Both resulted in poor and glitchy behaviour in some browsers. It also raised a problem with our default image caching: the service we use to return the images is a serverless real time image editor providing images with 10 minute cache; this means that if a user stays in the page for more than 10 minutes and then he interacts with the product view, the browser will download each frame as needed resulting in a very bad experience, unless we pre-fetch all the frames again.</p><p>So we changed approach: use a canvas to display the current frame. <br>With this technique we download every image at the initialization time and then draw the first frame in the canvas; there is still a drag listener that draws a different frame based on how far the user moves the mouse. <br>Surprisingly, this resulted in a very good and smooth experience with no cache problems and was very quick to implement.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*V8W3x24eVCR1pDwOOgwUlg.jpeg" /></figure><p>Supported by such good result we pursued the idea of implementing our own 360degree component.<br>We were able to achive every requirement we set, compatible with every browser altought with some challenge in enabling zoom, pan when zoomed and rotate when zoomed features.</p><p>The key challenges that we encountered were:</p><ul><li>Making it fully compatible with IE9–10: to implement the pan and zoom features we used <a href="https://github.com/timmywil/jquery.panzoom">a jquery plugin</a>; one of its drawbacks is that this plugin listens and ‘absorbs’ almost any user event that is triggered in the DOM tree where is instantiated; to overcome this problem we put a DOM element above the one that manages the zoom and we listen for every event there, filtering and proxying events to the lower jquery layer: we process just the click or touch events to rotate the content and let the other events bubble up to the zoom handler.<br>To make it fully compatible with IE9–10 we had to create this layer as a fully transparent image in a <em>img</em> tag instead of a simple <em>div</em> or <em>span</em> because those browsers have a bug that prevents some events from firing on transparent <em>divs</em> and <em>spans</em>.</li><li>Adapt image quality when the window resizes: when the player is instantiated we download images with the exact size of the div where they are created, this optimizes the bandwidth required and maximises quality of image. This, unfortunately, also leads to the need to manage image size/quality when the user enlarges the browser or when he sets the player in full screen. To prevent visible artifacts, when we detect a resize event, we start downloading in background the bigger frames and when each donwload session finishes we replace the previous image with the higher quality one.</li><li>To optimize performance we call requestAnimationFrame to draw in the canvas only when the user is interacting with the content, this is a nice practice to improve performance, battery usage and responsiveness of the host page</li></ul><p>Not reusing an existing library allowed us to create a model that easily fits into the existing player codebase and it was very easy to implement the customization features by reusing the player’s existing approach.</p><p><strong>There are, of course, some drawbacks in our implementation too</strong></p><p>In the current implementation, the player downloads every frame on the first user interaction thus causing, especially if content is composed by lots of images, more wait time than desired (similar to <a href="https://www.ajax-zoom.com/">this</a>). <br>This is mitigated by the fact that, thanks to our real time image editing service: we generate the images at the exact size needed for the rendering by using just the needed bandwidth and nothing more. Still, it’s not as good as a “streaming” approach. <br>We saw that some of the libraries, especially when the user zooms in, were using a backend service to receive just portions of images to minimize the number of KB that the user had to download, we could have used the real-time image editor features to achieve the same freature but unfortunately we couldn’t implement this feature and meet the deadline as well, so we plan to optimize this behavior in the future.</p><p>Another similar issue is that if the user creates a product view using frames with transparency (e.g. 60 PNG as frames) it will probably be a slow loading one. This is due to transparent PNG’s being heavier than Jpg’s. <br>We mitigate this, again, by using our real-time image editor: images are returned as png’s only if they really have transparency, otherwise they will be converted to jpg and cached for 1 year. This completely removes the problem when the content has png’s without transparency, but doesn’t improve performance on transparent 360 degree product view frames.</p><p>This project has been released in production already and is being used by customers and partners right now. We are pretty happy about it, especially because the customization is seamlessly integrated with the rest of the player components.</p><p>We would like to improve it in the future applying the backend support to improve the load/zoom performance</p><p><strong>So what did we learn during this journey? </strong><br>In analysis step we were sure that we were going to find something perfect for our needs, being able to shorten development times. By doing this we underestimated our requirements and this taught us to do a better analysis on requirements and to scout a bit earlier for technologies to understand whether it’s better to create our own or buy something ready to use. The challenge lies in the ability (or inability) to quickly estimate the effort to perform the scouting on existing solutions and estimate “make time”, we used a timeboxed approach to fix the amount of time we could dedicate to this research but we still feel this could have been managed in a more efficient way.</p><p>At the end, developing our own component might feel like reinventing the wheel but gave us a chance to optimize for our specific requirements and achieve the best result possibile for the end user, providing consistend apis and models that also helps partners in their learning process.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4813448410dd" width="1" height="1" alt=""><hr><p><a href="https://medium.com/thron-tech/buy-or-make-dilemma-can-be-hard-in-frontend-development-the-360-product-view-case-4813448410dd">“Buy or make” dilemma can be hard in frontend development: the 360 Product View case</a> was originally published in <a href="https://medium.com/thron-tech">THRON tech blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>