Forem: platformOS

2023 — A Year of Innovation and Growth for DocsKit

Tamas Simon — Fri, 09 Feb 2024 18:43:04 +0000

Reflecting on the incredible journey and growth we've experienced together in 2023, we can celebrate many significant milestones. The launch of our documentation platform, DocsKit is just the beginning, here's a summary of all the exciting highlights.

DocsKit is open-source, licensed under the terms of the Creative Commons Attribution 4.0 International License. Separately, platformOS offers a range of services, including setup, hosting, support, accessibility, sustainability, SEO, and performance packages.

User research

When we developed the award-winning platformOS Developer Portal, we conducted extensive research over several years into all aspects of documentation. This included its target audience, editorial workflow, features and functionality, accessibility, sustainability, and much more. We also delved into existing research and developed an empathetic understanding of how end-users, technical writers, editors, and contributors interact with documentation.

Using all this experience and research, we set out to build our own documentation solution to share with the platformOS partner community. Our goal was to ensure that a customizable solution covers all their documentation needs in a manner consistent with industry standards and best practices.

Of course, as always, we started with research again, conducting a competitive analysis and held discussions with documentation experts to shape our understanding of the ideal documentation solution for their needs. We continued user research at different development phases and haven't stopped. We hope that through this approach, we can consistently provide a documentation solution that exceeds our partners’ and clients' evolving needs.

Development and launch

Based on previous and new research, we began developing the architecture and features of DocsKit. Integrating Gatsby, GitHub, and platformOS, we built a solution that can function both as a standalone documentation site hosted on platformOS or as part of the platformOS modules ecosystem. This integration means it works seamlessly with other platformOS modules and kits. For example, it utilizes the platformOS DesignKit as its design system. Additionally, thanks to its Gatsby component, DocsKit can integrate with any of the 3000+ Gatsby plugins.

We launched DocsKit with a strong selection of features, enabling the creation of a complete documentation site, including an editorial workflow and automated CI/CD. During our soft launch, we reached out to partners for testing and feedback, and we have since incorporated all the feedback we received.

For instance, we made the GitHub repository for our DocsKit site public. Built entirely on DocsKit, this site's code and automation are now open for exploration.

In preparation for the launch of our Docs as Code educational series, we developed the course module as an extension to DocsKit. This module allows you to enhance your documentation site with video training and courses, along with downloadable content, and as a platformOS module, it can be used for any platformOS site.

Design

In parallel with development, we've also crafted the theme included in the DocsKit package to ensure it offers a fully customizable design, featuring an accessible and responsive theme. Key features encompass SEO readiness, responsiveness, optimized images, automatically generated navigation, table of contents, and breadcrumbs. The theme leverages Gatsby's Shadowing API, empowering users to implement a custom color scheme. Everything in the DocsKit theme adheres to the naming and format conventions of platformOS's public design system, the platformOS DesignKit. Furthermore, DocsKit provides the flexibility to use the Shadowing API for extending or overriding built-in components, enabling a high level of customization.

Out of the box, DocsKit offers a diverse selection of pre-designed custom components for use in MDX pages, enhancing the ease and efficiency of your documentation creation. Users also have the freedom to create unique versions of components, like the Button, by copying the original component file and adding customizations.

To assist DocsKit users in conceptualizing the content for their documentation site's landing page, we have introduced the Landing Page Content Collector — a FigJam brainstorming board tailored for non-designers. This board simplifies the process of promoting content from the comprehensive documentation to the landing page in a structured format. As of the time of writing this article, the user base has grown to a commendable 630 users, and we are delighted to learn that our Landing Page Content Collector is proving valuable to its intended audience and likely beyond. While specifically crafted to meet the needs of DocsKit users, this versatile board can be widely utilized for brainstorming any landing page content or for designing page layouts.

Knowledge sharing

We believe that sharing knowledge is crucial for growth and innovation. Having gained a thorough understanding of documentation, we are happy to share our insights with DocsKit users and the broader documentation community.

DocsKit Developer Portal: We began developing the DocsKit Developer Portal simultaneously with the launch of DocsKit. Incorporating insights from research, feedback, and experiences with clients and partners, we are organically expanding our developer portal to become the most reliable resource for all DocsKit users. This year, our plan is to incorporate additional useful, practical information and real-world examples, along with offering straightforward onboarding through a DocsKit sandbox.
Articles: Our articles section covers a range of topics, from Docs as Code and documentation standards to best practices in technical writing. It includes:
- Educational resources related to the core principles of technical writing.
- DocsKit news, updates, and announcements.
- Invitations to courses and webinars.
Case studies: Our DocsKit site now boasts a dedicated case studies section, offering valuable insights into the practical applications of DocsKit. We present two distinct types of case studies:
- Feature case studies: Illustrating how specific DocsKit features address common challenges, complete with practical examples and code snippets.
- Site case studies: Showcasing fully implemented DocsKit sites.
University course: We are currently working on a course curriculum for the University of Szeged, which will cover the entire product development life cycle for a PaaS application. platformOS serves as the main example, with DocsKit illustrating documentation, accessibility, and sustainability aspects.
Docs as Code Fundamentals course: Our Docs as Code Fundamentals course, starting in January 2024, provides a comprehensive understanding of Docs as Code. Ideal for beginners and those refining their skills, the course covers the basics to the editorial workflow. Sign up for the course to access videos for each lesson and participate in interactive webinars for deeper engagement with the instructor and our team.

Partnerships

DocsKit is now accessible for any platformOS Partner. Furthermore, we are actively collaborating to establish a network of specialized partners focused on DocsKit development for documentation sites. This initiative aims to provide clients with the option to choose a partner with expertise in DocsKit when they decide to create a DocsKit site.

For clients interested in directly working with the DocsKit team, we've initiated discovery calls where we introduce key features and benefits, compare DocsKit with open-source and SaaS solutions, discuss integrations, showcase example DocsKit powered sites, and outline pricing.

These initiatives aim to empower individuals and organizations with the knowledge they need for effective and sustainable documentation practices. Stay connected with us for the latest updates and opportunities to enhance your documentation skills!

Originally published at docskit.platformos.com

Background images in TailwindCSS - the clean and easy way

Paweł Kowalski — Thu, 14 Oct 2021 12:12:26 +0000

My biggest issue with TailwindCSS was the ugly way of using background images with it. I had to inline background-url property and it was not clean. And I know I was not alone, because other frontend developers said the same thing. It looked similar to this:

<section class="bg-accent-dark bg-cover"
  style="background-image: url({{ 'images/home/hero.jpg' | asset_url }})">

Note: We use liquid to generate url to an image placed on CDN.

Couple days ago, when I was doing six different themes in TailwindCSS using six different configs (I will report my findings in another article) I discovered that it can be simplified. Because CSS file is also on CDN, and the background-image can be customized in TailwindCSS config (read more), it can be replaced with simple bg-hero after adding its definition into theme extend section:

backgroundImage: {
  'hero': "url('../images/home/hero.jpg')"
}

Now, our hero element HTML looks like this:

<section class="bg-accent-dark bg-cover bg-hero">

And I think its much cleaner! Reading documentation paid off :)

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

Using WebP in Your Existing Webpage

Paweł Kowalski for platformOS ・ Nov 17 '20

#webperf #design

Optimizing Images For The Web

Paweł Kowalski for platformOS ・ Apr 24 '20

#beginners #node

3 Tips on Preserving Website Speed

Paweł Kowalski for platformOS ・ Jun 24 '20

#webperf #webpack #javascript #css

We Are Switching From TestCafe to CodeceptJS – Here’s Why

Paweł Kowalski — Tue, 28 Sep 2021 08:02:24 +0000

We have been using and promoting TestCafe at platformOS for the past couple of years with great success. Because a lot of people will write tests and maintain them over a long time, an End-to-End framework has to come with some specific requirements:

Easy to remember and type out API
Good waiting mechanisms (for XHR requests, animations)
Extendibility, page object support, helpers support
Good search in documentation to quickly reference less used APIs
Run properly in Docker and/or GitHub Actions

TestCafe is scoring high on the above areas, I would say averaging around 7.5/10, which means there is still room for improvement.

Even though we have been happy with TestCafe, last year when I stumbled upon a new contender, CodeceptJS, I decided to give it a shot on our documentation and marketing sites. It delivered excellent developer performance. It was enough to dive deeper into its documentation and expand our test suites to include some more test cases.

1. Test API

Very often when writing TestCafe tests, we had to resort to vanilla JS and DOM operations. One of the most frustrating examples was to get some text from an element and then compare it to another. It was too much work and I never could see a reason why TestCafe had no API for that. CodeceptJS has a lot more API helpers to avoid these complications and diverging into vanilla JS. Below, I give you some examples of TestCafe scenarios converted to CodeceptJS ones.

Checking if correct breadcrumbs links are present on a page

// TestCafe
test('Breadcrumbs are showing up', async t => {
  await t.navigateTo('/api-reference/liquid/introduction');

  await t.expect(Selector('.breadcrumbs a').withText('Documentation').exists).ok();
  await t.expect(Selector('.breadcrumbs a').withText('API Reference').exists).ok();
  await t.expect(Selector('.breadcrumbs a').withText('Introduction').exists).ok();
});

// CodeceptJS
Scenario('Are showing up', ({ I }) => {
  I.amOnPage('/api-reference/liquid/introduction');

  I.see('Documentation', '.breadcrumbs');
  I.see('API Reference', '.breadcrumbs');
  I.see('Introduction', '.breadcrumbs');
});

If this is interesting to you read rest of this article on our blog.

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

platformOS Documentation Site Webpack Setup

Paweł Kowalski for platformOS ・ Dec 4 '20 ・ 6 min read

#webperf #webpack #platformos

3 Performance Tips for Your Next Project

Paweł Kowalski for platformOS ・ Jun 29 '20 ・ 4 min read

#webperf #javascript #css

Should You Always Care about Your Website Size?

Paweł Kowalski for platformOS ・ Nov 12 '20 ・ 4 min read

#webperf #webdev #beginners

How We sped Up Our Webpack (TailwindCSS) 7 times!

Paweł Kowalski — Wed, 07 Apr 2021 17:20:31 +0000

In the last article about build speed optimization, we described how we went from 64 seconds to 17 seconds on our Webpack build (measured on GithubActions, a pretty slow environment CPU-wise). Just as we did it and managed to write an article about it to share the knowledge, something amazing happened: TailwindCSS/JIT.

JIT (short from Just In Time) for TailwindCSS is a much more performant way of generating the TailwindCSS output file. Instead of generating a big (sometimes 10MB+) CSS file and then using PurgeCSS to remove unnecessary classes, it only generates what is needed in the first place. This makes PurgeCSS and many other speed optimization techniques in TailwindCSS unnecessary. It is very fast no matter what config you use, and the output file size is still optimal.

We jumped into experimenting with JIT as soon as it got a beta release, so there were some bugs, but now we consider it good enough for production, hence this article.

Result: Webpack build took 8.9 seconds (down from 17)

As a nice side-effect of using JIT, our TailwindCSS config became much smaller because we don't need to disable modules, override theme colors, spacing, etc. Now everything is taken care of by JIT during runtime. It is so fast that development became a breeze.

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

platformOS Documentation Site Webpack Setup

Paweł Kowalski for platformOS ・ Dec 4 '20 ・ 6 min read

#webperf #webpack #platformos

3 Performance Tips for Your Next Project

Paweł Kowalski for platformOS ・ Jun 29 '20 ・ 4 min read

#webperf #javascript #css

Should You Always Care about Your Website Size?

Paweł Kowalski for platformOS ・ Nov 12 '20 ・ 4 min read

#webperf #webdev #beginners

How We Sped Up Our Webpack (TailwindCSS) Build By 74%

Paweł Kowalski — Mon, 22 Mar 2021 10:23:55 +0000

Since Github Actions became a thing, I became interested in saving precious seconds in our plan by optimizing assets build time. As long as it didn't exceed 60 seconds, there was little motivation, but once it did, I said enough is enough.

Our build step runs two commands:

npm ci
npm run build

We use babel and TailwindCSS. Using simple methods, I discovered that CSS and JS take about the same time to build.

Benchmark: Webpack build took 64 seconds, whole build took 91 seconds.

Replacing babel-loader + terser with esbuild loader

The first thing I did was replace babel-loader and Terser (minification tool) with esbuild-loader. This made our JS compile around 12 times faster, it went down to 1.4 seconds. It was a good start.

Result: Webpack build took 40 seconds (down from 64), whole build took 65 seconds.

Configuring Tailwind

The second optimization had to do something with CSS because that's where most of the build time now lay. I visited the TailwindCSS documentation to find out how to decrease build size.

The template we base our projects on uses a style guide with predefined colors, sizes, etc., so we don't need some of the configuration from TailwindCSS. Knowing this, here's what I did:

Moved colors configuration outside extend, which disabled all the built-in colors from the build. This made a huge difference in development file size (10.5MB → 4MB).
Moved spacing configuration outside extend
Disabled corePlugins

I had to bring some of these back because we used them in a couple of places. After these changes, I considered TailwindCSS optimization done.

The file size of development CSS went down from 10.5MB to 3.9MB, which is a big deal (depending on the developer's connection speed) if you are sending your CSS on every CSS change. It does not happen often when working with TailwindCSS, but it was still a welcome improvement for everyone using our pos-cli sync command.

Result: Webpack build took 26 seconds (down from 40), whole build took 49 seconds.

Read about TailwindCSS optimization in their documentation:

Disabling PostCSS processing

The last step was to disable PostCSS processing of CSS pulled in from node_modules.

Before, it was pretty naive — everything went through all the CSS loaders:

{
  test: /(\.css)$/,
  use: [
    MiniCssExtractPlugin.loader,
    { loader: 'css-loader', options: { url: false } },
    'postcss-loader',
  ],
},

I split it into two so that node_modules are processed only by css-loader, and application CSS is processed by PostCSS first.

{
  test: /(\.css)$/,
  include: /node_modules/,
  use: [
    MiniCssExtractPlugin.loader,
    { loader: 'css-loader', options: { url: false } }
  ],
},
{
  test: /(\.css)$/,
  exclude: /node_modules/,
  use: [
    MiniCssExtractPlugin.loader,
    { loader: 'css-loader', options: { url: false } },
    'postcss-loader',
  ],
},

Result: Webpack build took 17 seconds (down from 26), whole build took 39 seconds.

That's all :)

This journey was one of those creative ones where you fiddle around, find gains in various places, and they add up. In this case, they added up to 52 seconds of savings for every build. And we build a lot, so this improves our developer experience and lowers the cost of CI.

Action	Webpack build time (seconds)	Whole build time (seconds)
At the start	64	91
Using esbuild loader	40	65
Configuring Tailwind	26	49
Disabling PostCSS processing	17	39

In the following article, I will report how development speedup is going because the TailwindCSS team just released the experimental TailwindCSS JIT, which might improve live development even further.

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

platformOS Documentation Site Webpack Setup

Paweł Kowalski for platformOS ・ Dec 4 '20

#webperf #webpack #platformos

3 Performance Tips for Your Next Project

Paweł Kowalski for platformOS ・ Jun 29 '20

#webperf #javascript #css

Should You Always Care about Your Website Size?

Paweł Kowalski for platformOS ・ Nov 12 '20

#webperf #webdev #beginners

Build and Host Anything with platformOS

Diana Lakatos — Tue, 16 Feb 2021 14:07:02 +0000

A getting started guide using an open source ecommerce Marketplace Template to learn from.

What is platformOS?

platformOS (pOS) is a model-based application development platform.

It's like Firebase and Heroku had a baby, but with a lot more flexibility and power. It's infrastructure agnostic, allowing your solutions to be deployed to AWS, GCP and (soon) Azure with all your DevOps taken care of.

Aimed at front-end developers and site builders, it supports any front-end development framework such as React, Vue.js, Angular, Bootstrap, and others. It supports a flexible and limitless API-driven development approach while providing enterprise grade DevOps-in-a-Box to spin up a hosted site and go live in minutes. You can build any solution including community sites, membership based ecommerce club sites, product marketplaces with complex logistics and payment integration, service marketplaces, advanced auctions sites, QA and forums — even stand-alone SaaS applications. (We already have a G2.com #1 ranked Digital Experience Platform built on platformOS)

This article will help you get started with pOS using our Product and Community Marketplace template — a fully functional marketplace built on pOS with features like user onboarding, product/service listings and ads, add-to-cart and checkout process, including online payment via Stripe.

Following the tutorial, you can deploy this code within minutes to have a list of working features and then be able to start customizing the back- and front-end code (without any limits!). You can preview the demo marketplace solution template at getmarketplace.co.

What you'll need

To get started, you'll need to register on the platformOS Partner Portal, an online interface where you can create, manage and configure your sites (called Instances).

To register on the Partner Portal, go to https://partners.platformos.com/accounts/sign_up, complete the form or use your GitHub or Google account. Once registered, you will get an email verification. Click on the Accept verification link to activate your account.

Setup and configuration

Step 1: Install the pos-cli

The pos-cli is a command line interface that helps you deploy configuration files and assets to your pOS site. You will need a recent version of NPM (Node Package Manager) that comes with Node.js installed on your computer to install the pos-cli.

Once you have Node.js installed, start your command-line tool (for example, Terminal on a Mac, or Git Bash on Windows), and enter:

npm install -g @platformos/pos-cli

If your Node.js is installed for all users you might need to use sudo to install npm packages globally:

sudo npm install -g @platformos/pos-cli

Use the following command to test the pos-cli:

pos-cli -v

If the pos-cli has been installed correctly, running this command displays the version of your pos-cli. If the pos-cli hasn't been installed, running this command gives a command not found error.

Step 2: Create Instance

To be able to deploy your site, you have to create an Instance on the Partner Portal. Instances have a URL, and they represent different development environments, like staging or production. We recommend creating a staging environment for going through the steps in this tutorial.

On the Partner Portal, in the menu on the left under Create, select Instance, and fill in the form:

Field	Description	Example
Name	The name of your Instance	mymarketplace
Tags	Enter up to 5 tags (optional). You can use tags to group your Instances, for example by project or client.	marketplace, test
Partner	Select the Partner the Instance will belong to.	MarketplacePartner
Data Center	Select an endpoint (staging or production).	STAGING

Select the Staging/Unbilled Billing Plan that appears, and click on the Create button.

Developing and deploying to a staging Instance is free. Once the Instance is created (in a couple of minutes at most), you'll get an email with a link to your Instance and other useful information.

Step 3: Add Instance to pos-cli

WARNING: Make sure you remember your Partner Portal account email and password --- you will need them to authenticate your environments. If you logged in using Google or Github, go to the Instance details view in Partner Portal where you will find the pos-cli command ready for copy and paste. It shows all the parameters you need, so in this case, you won't need to remember your password.

On your local environment create a new directory and change to it. This is where you will put the codebase for your marketplace.

mkdir marketplace
cd marketplace

Add your Instance to the pos-cli. This will ensure that you can use the pos-cli to download your codebase, and sync or deploy to the Instance.

Use the pos-cli env add command and authenticate with your Partner Portal credentials.

TIP: You can copy this command pre-filled with your email and Instance URL from your Instance page on the Partner Portal.

pos-cli env add [YOUR_ENV_NAME] --email [YOUR_EMAIL] --url [YOUR_INSTANCE_URL]

For example:

pos-cli env add staging --email john.smith@example.com --url https://mymarketplace.staging.oregon.platform-os.com

A message "Environment [your Instance URL] as staging has been added successfully." is displayed.

Step 4: Clone the repository

Create your codebase by cloning our marketplace GitHub repository:

pos-cli init --url <https://github.com/mdyd-dev/product-marketplace-template.git>

Step 5: Build assets

Install the marketplace package and any packages that it depends on then build it using npm commands.

npm install
npm run build

Step 6: Deploy

To be able to display your marketplace on your site, you have to deploy your codebase using the pos-cli deploy command.

pos-cli deploy [YOUR_ENV_NAME]

For example:

pos-cli deploy staging

A progress indicator shows that the deployment is in progress, and once it finishes, a "Deploy succeeded after [time]" is displayed.

Step 7: Set up your marketplace

To access the admin panel of your marketplace:

Register a user with this email address: admin@example.com.
Enter the Admin section from the main menu.
Go to the Marketplace Setup section.

Congratulations, you have successfully created and deployed your first pOS site. Visit your Instance URL to check it out.

Next steps

Visit the pOS documentation to explore all that you can do with pOS. Follow step-by-step Get Started tutorials for beginners, or delve into more advanced topics using the Developer Guide. To meet and learn from fellow developers developing solutions on pOS, join the platformOS Community.

The platformOS UX/UI Process

Mónika Alföldi-Zörgő — Thu, 21 Jan 2021 11:00:49 +0000

We are not a UX/UI agency, but there’s consensus at platformOS that User Experience and User Interface Design are integral part of our processes. Although UX/UI teams usually choose from the same pool of methods and tools, no two processes are the same. This article describes how we do things at platformOS including UX/UI research and design, communication and learnings.

People and tools

We believe that one of the main strengths of our UX/UI process is teamwork. Our team consists of a UX researcher, a UX designer and a UI designer.
We have always worked remotely: we use Zoom for our calls, Figma for everything UX/UI related, and Miro for remote workshops.

First steps first

We ask the client to fill out our Strategic and design brief document. It contains basic questions about their challenges, strategic objectives, unique value propositions, history, purpose, problems they want to solve, their target audience, and competition. Depending on the project complexity and how detailed answers we get in the homework, the actual kick-off can be done in a maximum 3-hour call with the main stakeholders. Here we break the ice, go through the answers the client gave, and make an inventory of the client’s resources.
We also agree on the processes we would like to use: means and frequency of communication, who to reach out to for various resources (copy, design guide, etc.) and the project timeline.

Research phase

User interviews

Organizing and conducting the interviews might be time consuming but it almost certainly will be worth the time and effort: UX only makes sense if you know who you are designing for. We can only solve our customer's problems by design if we understand their user's goals and the context of use. This is a key moment for a successful project.

“Learn” the client and the product

From the UX point of view we study all the resources we have from the client to learn their vocabulary, understand their way of thinking and get in the same boat.
As for UI design, we study the brand guide, the current site if it is a redesign, and create an inspirational mood board with pictures and illustrations.

Get to know the competition

We get a full picture of the features, strengths and weaknesses of competitors, to be able to place the product correctly. It also helps us to understand the unique value proposition of the product.

Deliverables

We visualize and analyze the research findings in an affinity map. It shows us the primary needs and current challenges of the users. This visualization has proven to be useful not only because it makes it easy to present and understand data, but it will still be easily scannable months later.

The affinity map we created based on our research for the pOS Community site

Based on the research findings and the interviews we also identify the differences in the target group and summarize them in user personas.

Our template for user personas

We like to keep all the deliverables in the same Figma file: this way we literally have everything in one place. It’s not only good for our team but also makes it easier for the customers to follow the project.

The typical structure of a project’s Figma file

UX Design

Journeys and IA

platformOS is a limitless development platform that gives you the flexibility to customize every aspect of your digital build. This also means that our clients often require complex features and flows. It is essential to discover and discuss all user journeys in detail together with the client. We always start with the main and the most complex journey, and then add all the others in detail. In many sites that we work on (many to many marketplaces, community marketplaces, community hubs) user journeys often cross each other so we use different colors to reflect the journeys of different target groups.

3 user journeys that make up the main flow of OndeCare

This is also the first point where we like to discuss the project with developers. They can give us invaluable feedback that can also eliminate problems that otherwise would emerge during the development phase and would make us change the central workings of the product. Cooperation between the project teams is essential for a successful project.

After we have enough information about the journeys and have all agreed on them we continue with the information architecture and the sitemap.

The sitemap of our latest project: OndeCare

Wireframes

The journeys and the sitemap tell us what screens we need, so we have almost everything to create the wireframes. However, we strongly believe that only content driven design can ensure the best UX and design solutions. On one hand the sitemap delineates what copy is needed for the wireframes, so the client can prepare it. On the other hand, by this point we have “learned the product’s and the client’s language” and can use it for the UX copy. If needed we work together on the content strategy and UX copy.

Our wireframing process starts with sketches about various ideas that, depending on their complexity, we sometimes discuss in the design team. We create high-fidelity wireframes from one or maximum two of the ideas that emerged during our discussions. We ask for feedback on these wireframes from two sources: from the developers to have their feedback on feasibility and possible unseen glitches, and from the clients to see if we managed to realize their ideas. These first round discussions can save a lot of time later: we don’t need to modify pixel perfect designs let alone implemented pages. The most time consuming part at this stage is to think through all the possible user journeys, plan for edge cases, create notifications and different states. We always use real content on the plans to make it flexible enough for all cases.

Ondecare homepage wireframe with actual content

We also create prototypes from the wireframes which can be a great tool to check the most complicated flows internally just as with usability tests. Depending on the project timeline we like to run usability tests during the planning phase to gather feedback from users fast and iterate the design based on their needs.

UI Design

The actual UI design phase starts with creating the style guide based on the brand defined colors and fonts.

Style guide of the pOS design system

Style guides are a great resource for designers and developers but we can’t expect our clients to put together the site from the components in their minds. The first wireframe that we create is always a landing page, most often the homepage, because it contains the greatest variety of sections and elements: graphics, texts and layouts. We create two versions of the homepage and the client can choose which one they prefer. Then we add all the elements that are used on the site to the style guide so that we can reuse them and have consistent design.

Two versions of the Ondecare homepage

Layouts and grids are an example of the essential things that we create during the high fidelity design phase. We always create layouts that can work both on mobile and desktops, and align all the elements based on these. We add the illustrations and modify them to match the brand colors. Talking about colors, we also put great emphasis on accessibility and contrast ratios. We create smaller (but equally important) pages like 404, under maintenance pages, and usually even an email template to be consistent everywhere.

As I mentioned we work as a team, which means that the wireframing and high fidelity design phase happen parallely: in our meetings with the client we present the wireframes and ask for feedback. It’s best if we can do the majority of necessary modifications on the wireframes, where we can focus more on the functionalities. Once a wireframe is accepted by the client, it is turned into a pixel perfect screen. Mobile versions can be created either in the wireframing or in the high fidelity design phase.

Figma is a great tool for design handoff, developers can easily export assets, but if necessary we collect all images and graphics for them.

Retrospective

Our process has been working well for us, but since there is no such thing as a perfect process we try to learn from each project. As a closing step for our process, we always hold a retrospective meeting where we check back to our flow and collect everyone’s experience. Our goal is to learn about the highlights and the improvement areas and to identify the necessary modifications for our next project.

For example, during our last project we learned that we needed to improve the way we sort our screens in Figma. We had two separate folders for wireframes and for pixel perfect designs which might not be optimal in each case: during implementation developers consult pixel perfect designs, but there are functional wireframes that don’t need to be turned into pixel perfect design, like confirmation popups. Based on the team's feedback in the next project we will put these next to each other on one page, so that we only have to check one page for the different states of a screen.

Of course every project is unique and they all have their own challenges, that we can only address if we handle our processes flexibly. But having this general framework helps us to stay consistent and not to leave out anything important, plus the client can have a clear picture throughout the project and know what to expect.

The platformOS UX/UI process was defined by our Director of UX Kata Nagygyörgy and Director of Visual Design Gyöngy Gora.

How to catch Front-end performance regressions?

Paweł Kowalski — Tue, 29 Dec 2020 15:14:01 +0000

If you try to take care of your visitors by making your website fast and light, you probably measure its speed using some tool. Chances are you use one of these free tools:

Today I will show you how to:

Run Lighthouse easily from your browser on your current page
Save report to JSON file
Compare past report with current report to see if your page is going in the right direction

What you will need

Only two things are needed to compare past report with current one.

Lighthouse extension for your browser:

And a website that will compare two reports:

Lighthouse CI Diff

Generate report

After you have installed Lighthouse extension go to your website. Open extension by clicking on its icon, change settings to include all reports and use Desktop strategy, and click generate report.

Note: You can use mobile strategy, or skip PWA - we do. The important thing is to stick to the settings because if Lighthouse report is generated using different settings, compare tool might have issues with detecting changes.

It should look something like this:

Now you can export this report to JSON file for future reference. In top-right corner there is a "three dot" menu, click it and generate JSON report. Save it in a safe place - you will need it.

When you have two reports, ideally generated between some changes, you can go to https://googlechrome.github.io/lighthouse-ci/viewer/ and upload both of them to compare. Upload the older one on the left (Base), and newer one on the right (Compare) - this way it will tell you if you made progress or not.

This is how generated comparison looks for our last two builds on our platformOS documentation site.

Future improvements

In the next post I will write how you can use Github Actions to do the reports automatically. It will give you link to comparison report on every pull request, so you can skip the boring parts and get to the good stuff. :)

If you like web performance, take a look at my other articles, you might find some inspiration there how to make progress without much effort. And if you really like web performance, consider following me :)

3 Tips on Preserving Website Speed

Paweł Kowalski for platformOS ・ Jun 24 '20 ・ 6 min read

#webperf #webpack #javascript #css

3 Performance Tips for Your Next Project

Paweł Kowalski for platformOS ・ Jun 29 '20 ・ 4 min read

#webperf #javascript #css

How platformOS uses mixpanel while keeping users privacy?

Paweł Kowalski — Sun, 20 Dec 2020 14:44:04 +0000

We at platformOS value our visitors privacy, time and money. And because we live by our values, we always dive deeper into technologies to manifest them. Today we will dive look into how we use mixpanel without breaking our website's performance or sacrificing our visitors privacy.

We use mixpanel to learn where our visitors are confused, leaving our pages

Why mixpanel

Mixpanel is an industry standard when it comes to getting to know what visitors are doing on your site.
It does not track everything like Google Analytics, but only what you tell it to. At least we hoped that would be the case, but looking at the documentation and training materials led us to believe that it is actually gathering more data than we were comfortable with giving or needed.

Having said that, mixpanel has a very comprehensive set of tools to dive deeper into where your visitors journey on your website. This is very important for onboarding process because you can focus on exactly the part that is a bottleneck, so you don't waste time optimizing the wrong part of it.

How mixpanel is usually implemented

Just like most third-party services mixpanel usually is implemented on the frontend, using javascript. This has a lot of consequences, no matter if you load the script from your CDN or from mixpanel CDN.

It has to load - your page becomes bigger (around 80KB bigger)
It has to parse and execute - your page becomes slower, especially on slower devices (mobile)
You don't really know what it does (or track), unless you are inspecting mixpanel javascript client codebase before installation and every update
According to documentation turning on GDPR compliance is an opt-in, so this might create additional friction and work to be done
AdBlockers have mixpanel CDN blocked by default, so there will be gaps in data. How big of a gaps? Well, some sources report 50% gaps, which is big enough to not rely on client-side measurements.

All those disadvantages are directly against our values. But mixpanel is good enough product to do the research and our great engineers found a way to use mixpanel without any javascript.

How we use mixpanel

Sending HTTP requests in platformOS is very simple, and we decided to leverage that in our implementation.

First we defined API call that will do the network call:

---
name: mixpanel_create_event
to: https://api.mixpanel.com/track
format: https
request_type: POST
callback: >
  {%- assign response_data = response.body | to_hash -%}
  {% if response_data.error %}
    {%- log response_data.error, type: 'modules/monitoring/mixpanel_create_event' -%}
  {% endif %}
request_headers: >
  {% if data %}
    {
      "Content-Type": "application/x-www-form-urlencoded"
    }
  {% endif %}
---
data={{ data }}

Everything between --- is definition of the api call, everything below, is the body of the request that will be sent. Additionally, callback is executed after the API call has been sent. In our case it is logging error if mixpanel server returned one.

Having defined API call, we need to execute whenever we need to, with proper data. Here we created another abstraction to be able to pass different events from different sources:

{% liquid
  graphql instance = 'modules/monitoring/instance' | dig: 'instance'
  unless data
    assign data = '{}' | parse_json
  endunless
  hash_assign data['distinct_id'] = instance.id
  hash_assign data['instance_id'] = instance.id
  hash_assign data['token'] = "377404cb3e579051250ca9a2b129ea7b"
%}
{% parse_json mixpanel_data %}
{
  "event": "{{ event_name }}",
  "properties": {{ data }}
}
{% endparse_json %}

{% liquid
  graphql r = 'modules/monitoring/api_call', data: mixpanel_data, template: 'modules/monitoring/mixpanel_create_event'
  log r, type: 'monitoring/migration/track_first_deploy'
  return r
%}

To every event we attach some basic data, like:

public token (required by mixpanel),
instance id - to know which website sent the event

And some variables that are passed down from different parts of the system, one is event_name which is just a name to filter them easier in the mixpanel dashboard, and data which is a JSON object that can contain anything we want, including user data, like id, email, browser data (extracted from user agent), etc.

Now we can call this piece of code (partial) anywhere in our application, passing event_name and some data. Simplest example would be our marketplace_install event which is called every time someone installs our Marketplace Template for the first time.

Event name is called marketplace_install to group all those events in one bucket. Our template has different variants (community site, ecommerce), so our data object identifies that so we know what type of marketplace our partners and clients are installing.

{% parse_json data %}
  {
    "marketplace": "products"
  }
{% endparse_json %}

{% liquid
  if context.location.host != 'getmarketplace-qa.staging.gapps.platformos.com'
    function res = 'modules/monitoring/commands/track_event', event_name: 'marketplace_install', data: data
  endif
%}

Profits

Using mixpanel server-side has some consequences:

There is no performance penalty at all on the frontend
There is no performance penalty on the backend, because code can be run asynchronously, so visitor does not have to wait until data has been sent to mixpanel when browsing website
Server only knows as much as browser tells it plus whatever logged in person provided, if anything
Mixpanel does not run any code on neither browser side or server side, so hypothetical hack, our clients are safe. You might think it is far-fetched and a non factor, but history teaches us that hack/leak is not a matter of "if" but "when", no matter how good of a security company implement. Thats one of the reasons we try to minimize data we keep, and give.

Tracking across multiple sites

When you have multiple sites like we do (Documentation, Marketing page, Partner Portal) you might want to track visitor's journey across all of them. We had this thought too, but this would mean one thing: identifying single users.

Long story short, it all comes down to fingerprinting which is a standard practice for most big outlets, ad networks, etc. but is unacceptable by us. Not only it is sending a lot of javascript down the wire that visitors does not want, they would probably answer: "NO" if you asked them if they want to be fingerprinted, no matter what.

Instead of tracking across multiple pages, we decided to restructure our onboarding flow a little bit to minimize jumping across different domains/websites. It is more consistent visually and more performant for the visitor as well.

Resources

[Video] What is mixpanel by Danny Lambert

Mixpanel Documentation

platformOS Documentation

platformOS Marketing page

platformOS product template github repository

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

Using WebP in Your Existing Webpage

Paweł Kowalski for platformOS ・ Nov 17 '20 ・ 4 min read

#webperf #design

Optimizing Images For The Web

Paweł Kowalski for platformOS ・ Apr 24 '20 ・ 8 min read

#beginners #node

3 Tips on Preserving Website Speed

Paweł Kowalski for platformOS ・ Jun 24 '20 ・ 6 min read

#webperf #webpack #javascript #css

platformOS Documentation Site Webpack Setup

Paweł Kowalski — Fri, 04 Dec 2020 18:25:30 +0000

Webpack is a powerful tool. Back in the day, it had a reputation of being hard to learn and hard to use. Nowadays, it has excellent documentation, sensible defaults, plugins, and loader - all this to help you keep your config small while achieving great results.

Important features in 2020

The most important features of webpack for our projects are:

Tree shaking
Code splitting
Dynamic async loading chunks of code

This article explains how we used webpack in our documentation for the past couple of years for easy development and performant production builds.

The final webpack config looks like this:

const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const WebpackRequireFrom = require('webpack-require-from');
const webpack = require('webpack');

const production = process.env.NODE_ENV === 'production';

module.exports = {
  entry: {
    'app': './src/app',
    'graphql': './modules/graphql/public/assets/graphql',
  },
  output: {
    chunkFilename: '[name].[chunkhash:3].js',
    publicPath: '',
    path: path.resolve('app/assets'),
  },
  module: {
    rules: [
      {
        test: /(\.css)$/,
        use: [MiniCssExtractPlugin.loader, { loader: 'css-loader', options: { url: false } }, 'postcss-loader'],
      },
      {
        test: /\.js$/,
        loader: 'babel-loader',
        options: {
          exclude: /node_modules/,
          plugins: ['@babel/plugin-syntax-dynamic-import', '@babel/transform-object-assign'],
          cacheDirectory: true,
          presets: [
            [
              '@babel/preset-env'
            ]
          ]
        },
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: '[name].css',
      chunkFilename: '[name].[chunkhash:3].css',
    }),
    new WebpackRequireFrom({
      variableName: 'window.__CONTEXT__.cdnUrl',
    }),
    new webpack.DefinePlugin({
      'process.env': {
        NODE_ENV: JSON.stringify(process.env.NODE_ENV),
      },
    }),
  ],
  mode: production ? 'production' : 'development',
}

Note about static assets

We do not process static assets with webpack. Fonts, images are just sitting already optimized in their proper place in our platformOS assets directory - app/assets. There are a couple of reasons we do that:

Manual optimization is usually better than automatic
Config is simpler
Fewer dependencies to break
Build is faster
We don't waste CPU time (= money) on CI doing the same operation on every build

Technologies

PostCSS is a framework for creating CSS parsing plugins. It allowed us to migrate away from SASS to reduce complexity. It handles some legacy browser fixes. It is also a base for TailwindCSS, a PostCSS plugin.

TailwindCSS is a CSS framework that makes it easy to create maintainable views with a minimal CSS footprint.

If you are interested in how we set up TailwindCSS and PostCSS, visit our documentation GitHub repository.

Base config

Out of the box, webpack can work with no config at all. Read more on prototyping with no config. By default, it looks for the index.js file in the src/ directory and outputs to dist/main.js. We need to use a couple of features, so we need a config file. The webpack settings we use are pretty simple.

Entry points

entry: {
  'app': './src/app',
  'graphql': './modules/graphql/public/assets/graphql',
},

We use two entry points (files that we will pull in from our HTML) because we have completely separate CSS files for our documentation page and autogenerated documentation for GraphQL endpoints. key is to define how the output will be named, value is the relative path to the file webpack will treat as an entry point. For example: app.js will be generated from entry point src/app.js.

Output

We don't define the output filename because by default, it is [name].js, and it works for our case. But for chunkFilename, we need to add chunkhash for cache invalidation purposes.

publicPath is set to empty because we will not use webpack's built in publicPath — we will use the one from WebpackRequireFrom, explained later.

path is the absolute path where the output files will be placed. In the case of platformOS, it is app/assets.

output: {
    chunkFilename: '[name].[chunkhash:3].js',
    publicPath: '',
    path: path.resolve('app/assets'),
  },

Plugins

MiniCssExtractPlugin extracts CSS to external files. Without it, webpack would package everything into one JS and one CSS.

new MiniCssExtractPlugin({
    filename: '[name].css',
    chunkFilename: '[name].[chunkhash:3].css',
})

The platformOS Liquid filter for getting the URL to assets placed on the CDN adds the query param to bust the cache, so the main files that we require in Liquid do not need to vary in between different builds. We add chunkhash:3 in the file name for chunks because those are loaded dynamically from webpack, and there won't be a query param to handle that.

Why all that? To prevent browsers from loading a file from cache (old asset could break something) if it changed.

Files loaded using the native platformOS asset_url filter:

Chunks loaded with chunkhash in the filename:

WebpackRequireFrom sets the CDN URL during runtime for dynamic chunks, so we don't have to hardcode anything. We just pull this URL from the HTML source, which is rendered server-side.

new WebpackRequireFrom({
    variableName: 'window.__CONTEXT__.cdnUrl',
}),

This option tells webpack where to look to get the CDN URL in the browser when the application is running. In Liquid, we define window.__CONTEXT__.cdnUrl to our CDN URL to let webpack know where to look for dynamically loaded chunks.

<script>
  window.__CONTEXT__ = { cdnUrl: "{{ '' | asset_url }}" };
</script>

This results in chunks loaded correctly on all environments provided by platformOS: dev, staging, and production.

The webpack.DefinePlugin allows us to pass build mode (production or dev) to the runtime. This is needed by the Algolia search script that we use as our search engine.

new webpack.DefinePlugin({
 'process.env': {
     NODE_ENV: JSON.stringify(process.env.NODE_ENV),
  },
}),

Keep in mind that for this line to work, we execute webpack-cli with NODE_ENV defined in the npm script.

"build": "NODE_ENV=production npx webpack-cli --no-color",

Loaders

Loaders are specific plugins for webpack that extend its functionality to operate on files that it does not understand by default. By default, webpack can only parse and bundle JavaScript.

The order of loaders matters. For example, css-loader cannot parse syntax written for PostCSS, so PostCSS needs to be executed first. Loaders are executed from right to left.

postcss-loader allows webpack to use the PostCSS plugins ecosystem. It usually needs the postcss.config.js file to add PostCSS plugins because PostCSS on its own doesn't do anything.

{
    test: /(\.css)$/,
    use: [
            MiniCssExtractPlugin.loader,
            { loader: 'css-loader', options: { url: false } },
            'postcss-loader'
        ],
},

For CSS files, PostCSS will do its thing first, pass the output to css-loader, it will do its thing (without resolving URLs in CSS) and pass the output to MiniCssExtractPlugin.loader which will save the CSS to separate files.

babel-loader transpiles JavaScript using babel and its plugins. We use preset-env and two plugins: syntax-dynamic-import and transform-object-assign for browsers defined in package.json.

Code splitting and conditional loading

This article wouldn't be complete if I did not include how to split code in webpack build time so that it asynchronously loads chunks while running in the browser.

import './app.css';

import { $q } from './js/helpers/dom';

import './js/sidebarMenu';
import './js/deepLinks';
import './js/autosteps'; // this HAS to be after deepLinks
import './js/toc';
import './js/externalLinks';
import './js/feedback';

import(/* webpackChunkName: "search" */ './js/search');

if ($q('code[class*="language-"]')) {
  import(/* webpackChunkName: "syntaxHighlighting" */ './js/syntaxHighlighting');
}

All the ES6 imports (from sidebarMenu to feedback) will be bundled directly into app.js.
Dynamic imports (function named import - search) will generate chunks, that will be loaded asynchronously.
Dynamic imports wrapped in an if statement will be loaded asynchronously only when the if condition evaluates to a truthy value. In our case, when a certain selector is present on the webpage. Webpack will not load those modules on pages that do not require them.

Example requests for the homepage:

Example requests for a page where syntax highlighting is needed:

Closing thoughts

Webpack in 2020 is a totally different beast than it was in 2015, but it can still be intimidating. If you don't feel its syntax, you can try different code bundlers; some of them are simpler to some people (rollup), and some are much faster (esbuild). We chose webpack a long time ago because it was reliable, the most feature-rich (thanks to plugins), powerful, and very well documented.

If you are interested in a Webpack + TailwindCSS setup for static websites (with HTML that you can deploy to platformOS, netlify, vercel, or just AWS S3), we created an opensource boilerplate for you to quickly jump in and test it out.

How to Test Slack Notifications

Paweł Kowalski — Thu, 26 Nov 2020 17:25:29 +0000

Marketing forms are often connected to a third-party system to help the marketing team provide faster and more accurate responses.

We integrated our contact page with Slack, HubSpot, SendGrid, and emails. Whenever someone fills in the form, we notify the appropriate people via email, Slack message, and create records in HubSpot and SendGrid for future management of those contacts.

One day we received the email, but the Slack notification did not come through, and this made me think about testing Slack notifications to catch regressions in this area.

To achieve this, we need two things:

A test channel for test messages
A test that will send the form for us

platformOS notification setup

platformOS API Call notifications support WebHooks, so that's what we used for Slack messages. The setup involves only a couple of lines of code, but the most important in the context of this article is the WebHook URL.

---
name: slack_landing_sales
delay: '0'
enabled: true
format: http
headers: '{ "Content-Type": "application/json" }'
request_type: POST
to: https://hooks.slack.com/services/XXX/XXX/XXX
trigger_condition: true
---
{
"text": "
Heads up! Contact from {{ form.properties.url }}.
Name: {{ form.properties.first_name }} {{ form.properties.last_name }}
Email: {{ form.properties.email }}
Phone: {{ form.properties.phone }}
Comments: {{ form.properties.description }}",
}

The line to change is the one with to: [https://hooks.slack.com/services/XXX/XXX/XXX](https://hooks.slack.com/services/XXX/XXX/XXX) which I censored. You need your own webhook URL to be able to send messages to your channel.

To not send test data to the production Slack channel, it is a good idea to differentiate production from everything else:

to: >
  {% if form.properties.url contains 'https://www.platformos.com' %}
  https://hooks.slack.com/services/XXX/XXX/XXX
  {% else %}
  https://hooks.slack.com/services/YYY/YYY/YYY
  {% endif %}

This if condition will check if the form field called url contains a particular string. Because we are populating it before sending the form, it is filled in with the URL of the instance. In the case of our production site, it is https://www.platformos.com.

E2E test in TestCafe

Now, we need to programmatically go through the form, fill it, send it, and validate that it has been sent successfully.

We use TestCafe for E2E tests. It is not too difficult to start using it if you have experience with testing.

import { Selector } from 'testcafe';
import { BASE_URL } from './env';
import faker from 'faker';

fixture('Contact').page(`${BASE_URL}/contact`);

test('Contact form works', async (t) => {
  const fn = Selector('[name="form[properties_attributes][first_name]"]');
  const ln = Selector('[name="form[properties_attributes][last_name]"]');
  const email = Selector('[name="form[properties_attributes][email]"]');
  const phone = Selector('[name="form[properties_attributes][phone]"]');
  const description = Selector('[name="form[properties_attributes][description]"]');
  const submitBtn = Selector('button').withText('SUBMIT');

  const notice = Selector('[role="alert"]').withText('Your contact form has been sent');

  await t
    .typeText(fn, faker.name.firstName())
    .typeText(ln, faker.name.lastName())
    .typeText(email, faker.internet.email())
    .typeText(phone, faker.phone.phoneNumber())
    .typeText(description, faker.lorem.paragraph(), { paste: true });

  await t.click(submitBtn);

  await t.expect(notice.exists).ok();
});

A short summary of what is going on here:

Importing TestCafe and faker (generates fake data so that the test varies every time it is run)
Telling TestCafe the URL at which the test will be run
Defining selectors for all the DOM elements we will be interacting with
Filling in all the data in the form
Submitting the form
Checking if the Your contact form has been sent message is visible after the form has been sent

Running the test in chromium results in a pretty video:

In your terminal, you should see something similar after running TestCafe:

> testcafe chromium tests --video artifacts --video-encoding-options r=20

 Running tests in:
 - Chrome 88.0.4295.0 / macOS 10.15.7

 Contact
 ✓ Contact form works

 1 passed (38s)

This means that the test passed, so now it is time to verify if the Slack notification came through. This is what this test generated:

Continuous Integration

To make our lives even more automated, we add the npm run test-ci command to our CI workflow. For this project, we use Jenkins, but you might use Github Actions, Travis, or CircleCI if you prefer. Remember that your CI server has to have a browser supported by TestCafe (see the list of officially supporter browsers here).

In our case, making tests run on every master branch run was similar to:

stage('Test on URL') {
    agent { docker { image "platformos/testcafe" } }
    environment { MP_URL = "${params.MP_URL}" }
    steps {
      sh 'npm run test-ci'
    }
    post { failure { archiveArtifacts "screenshots/" } }
}

We also use a different command on CI because we want to take screenshots of failures only and run the test in a headless browser (it is much faster — the test above runs in 6 seconds instead of 38):

testcafe 'chromium:headless' --screenshots-on-fails --screenshots=screenshots tests

Now every time any code is merged into the master branch, TestCafe will test this form and trigger the Slack webhook. If the message will be missing one day, or if the test fails, we will know something is wrong either on our side or Slack's.

Resources

I hope this guide will help you avoid some of the regressions. Here are some resources that you might find useful if you decide to follow our path:

platformOS Website

platformOS Documentation

Slack - Creating App with WebHooks

TestCafe testing framework

faker npm package

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.

Using WebP in Your Existing Webpage

Paweł Kowalski for platformOS ・ Nov 17 '20

#webperf #design

Optimizing Images For The Web

Paweł Kowalski for platformOS ・ Apr 24 '20

#beginners #node

3 Tips on Preserving Website Speed

Paweł Kowalski for platformOS ・ Jun 24 '20

#webperf #webpack #javascript #css

Using WebP in Your Existing Webpage

Paweł Kowalski — Tue, 17 Nov 2020 14:44:16 +0000

If you are checking your website's performance using Lighthouse, you might have noticed that one recommendation is to use "Serve images in next-gen formats" and by that, they mean WebP.

According to Google, if you compress PNG images, you will save 26% on average.

Compared to JPEG with a similar SSIM setting, the difference is even more significant — 25%-34% depending on image type. We tested those claims on our JPEG photos from a smartphone, read on to learn about the results.

Note: Be careful what type of image you compress with WebP because it has no progressive loading like JPEG, so your hero image in WebP might negatively impact First Contentful Paint.

Harry Roberts

@csswizardry

Fascinating issue on a current client site where we reduced their masthead image weight by over 20% by switching it to WebP. It’s now rendering almost 2× later because WebP doesn’t offer progressive rendering like the previous JPG did.

19:55 PM - 05 Nov 2020

If WebP is so good, why isn't everyone using it?

In short: Tooling.

Your phone takes photos in JPEG.
Your computer takes screenshots as PNG or JPEG.
When you download images from a stock photo service, it's JPEG.
Logotypes are often SVG.
Your operating system most likely does not know how to preview WebP natively, so you need to download special software to do it.

All these are barriers to adoption for this format, which apart from having better compression, has an alpha channel, which is missing from JPEG.

Our case

One day, looking at a performance report from our social commerce marketplace template (see live demo at: https://getmarketplace.co/ ), I decided to do something about it and add WebP versions of the biggest images.

Why only the biggest images? Because the bigger the image, the bigger the savings.

Saving 20% from a 9 KB lazy-loaded image is a good thing, but saving 20% from 3 images eagerly-loaded, 500 KB each, is much better.

Browser compatibility

Not all browsers support WebP, so you'll need a fallback for those browsers. Luckily, the picture HTML tag takes care of that.

Read about browser support for WebP at caniuse.com: https://caniuse.com/?search=webp

In any case, you can use WebP nowadays with a fallback to JPEG - read how to do it (and more) in this excellent CSS-Tricks article.

platformOS image versions

Users very rarely have images in an optimal format or version. Often users upload photos straight from their camera or photos in PNG format. More often than not, you want to recompress those images to fit your performance and quality vision. We implemented a feature that allows the site owner to decide what to do with user-uploaded images.

After the user uploads the image directly to cloud storage to speed up things by eliminating intermediaries, a function takes the original file and generates new versions based on the configuration defined in a YML file. It usually takes so little time that the user will not notice when it happens, as it happens in the background, asynchronously.

In our case, the basic configuration looked like this:

name: photo
properties:
  - name: photo
    type: upload
    options:
      versions:
        - name: uncropped
          output:
            format: jpeg
            quality: 80

This means whatever image the user uploads will be available to use in its original form and an additional JPEG file will be generated called uncropped with quality 80. We wanted to also have this image in WebP format, so I added the second version to the array:

- name: uncropped_webp
  output:
    format: webp
    quality: 70

HTML and Liquid

To show the images we have to get objects from GraphQL and retrieve URLs to the generated versions:

<picture>
  <source srcset="{{ p.photo.versions.uncropped_webp }}" type="image/webp" alt="{{ item.name }}">
  <source srcset="{{ p.photo.versions.uncropped }}" type="image/jpeg" alt="{{ item.name }}">
  <img src="{{ p.photo.versions.uncropped }}" alt="{{ item.name }}">
</picture>

Results

I uploaded three photos straight from my smartphone:

[3.5M]  IMG_20201105_144639.jpg
[4.2M]  IMG_20201109_194144.jpg
[3.2M]  IMG_20201115_001933.jpg

They are very big in terms of dimensions (4608x2592 px) and size, so I expected to see a lot smaller files at the end of this experiment.

Recompression to quality 80 in JPEG gave pretty good results:

[1.5M]  uncropped_IMG_20201105_144639.jpg
[1.9M]  uncropped_IMG_20201109_194144.jpg
[1.3M]  uncropped_IMG_20201115_001933.jpg

Let's compare them to the WebP version (quality 70):

[1.0M]  uncropped_webp_IMG_20201105_144639.webp
[1.0M]  uncropped_webp_IMG_20201109_194144.webp
[996K]  uncropped_webp_IMG_20201115_001933.webp

The images vary in many ways, including color distribution or the numbers of edges. Because results depend on image content, an average is most often used when describing compression results. The smallest difference was 23%, and the biggest was 48%. That's a huge variance. In total, those three images saved 1.7 MB.

Summary

├── [ 11M]  original
│   ├── [3.5M]  IMG_20201105_144639.jpg
│   ├── [4.2M]  IMG_20201109_194144.jpg
│   └── [3.2M]  IMG_20201115_001933.jpg
├── [4.7M]  processed-jpeg
│   ├── [1.5M]  uncropped_IMG_20201105_144639.jpg
│   ├── [1.9M]  uncropped_IMG_20201109_194144.jpg
│   └── [1.3M]  uncropped_IMG_20201115_001933.jpg
└── [3.0M]  processed-webp
    ├── [1.0M]  uncropped_webp_IMG_20201105_144639.webp
    ├── [1.0M]  uncropped_webp_IMG_20201109_194144.webp
    └── [996K]  uncropped_webp_IMG_20201115_001933.webp

Saving 1.7 MB (or 36%) on three images without noticeable quality degradation is a success in my book. We could turn up the quality knob higher, and we'd still have plenty of headroom not to lose any detail at all. It is a good result for a couple of lines of code. Especially if the image you are optimizing is a crucial piece of content (in our case, an item photo) and not some stock photo.

If you want to check out how the files are different visually, you can view them on my GitHub.

Additional resources

If you are interested in more performance oriented content, follow me and I promise to deliver original, or at least effective methods of improving your website.