Forem: Factorial GmbH

What's new in phabalicious 3.8?

Stephan Maximilian Huber — Mon, 22 Aug 2022 12:36:52 +0000

What has changed?

PHP 7.3 required

Phabalicious requires now PHP version 7.3. It should work with newer versions, including 8.1

Better integration with 1Password cli/ connect

Support for version 2 of the cli
added new script callback get_file_from_1password which will retrieve an encrypted file from 1password, decrypt it and store it somewhere, suitable when scaffolding.

Encryption and decryption

Phab supports now encryption and decryption of files and strings. It uses defuse/php-encryption,
a widely used library for encryption under the hood. You can encrypt files in a script with

secrets:
  name-of-secret:
    question: What is the password?

scripts:
  encrypt:
    - encrypt_files(path/to/files/or/folders/to/encrypt/*.ext, path/to/folder/to/store/encrypted/files, name-of-secret)
  decrypt:
    - decrypt_files(path/to/files/or/folders/to/decrypt/*.enc, path/to/folder/to/store/decrypted/files, name-of-secret)

The scaffolder has a new callback called decrypt_assets which works the same as copy_assets but with an additional
decryption step

scaffold:
  - decrypt_assets(targetFolder, dataKey, secretName, twigExtension)

You can also use decrypt() and encrypt() in your scaffold templates using the provided twig-functions:

test.yml

data:
  my_secret_data: "{{ decrypt(my_secret_data, 'name-of-secret') }}"
  encrypted: "{{ encrypt("Hello world", 'name-of-secret') }}"

New command `install:from-sql-file`

The command install:from and the new command install:from-sql-file get reworked to prevent double-work and to
streamline the process. You can now install the app from an existing sql-file, which translates into an optimized
flow of

phab -cmy-host-config install
phab -cmy-host-config restore:sql-from-file sql.gz
phab -cmy-host-config reset

Instead run

phab -cmy-host-config install:from-sql-file sql.gz

Refactoring of data-handling

Phab now handles data differently, by storing from which file or url a piece of data was loaded. This enables phab to
use relative includes, even for remote configurations. Now you can do things like

base.yml

hosts:
  test:
    foo: Hello world
    bar: Hello from base.yml

fabfile.yml:

inheritsFrom:
  - ./base.yml

needs:
  - local

hosts:
  test:
    foo: Hello mars

Running output will show the resolved inheritances:

❯ phab38 -ctest output --what host


Output of host-configuration `test`
===================================

  test:
    foo: 'Hello mars'
    bar: 'Hello from base.yml'
    needs:
      - local
      - script
    type: dev
    .
    .
    .

This enhances also the introspection possibilities:

The about command got a `-v` flag

The about command has another trick up its sleeve now. When inheriting configurations from multiple files, it can now
display the exact location from which a particular parameter is being picked. Thus, finding out if a value is coming from an inherited file from a remote server or some sensible defaults is at your fingertip.

Let's have a look at an example to see this in action. The command displays not only the active value for a particular
key but also the location from which it is picked up.

In our case the ouput of phab -ctest about will show the inheritance very in the second column:

❯ phab about -v -ctest

Configuration of test
=====================

+-----------------------------+-------------------------------------+---------------------------------------------------+
| Key                         | Value                               | Inherited from                                    |
+-----------------------------+-------------------------------------+---------------------------------------------------+
|   foo                       | Hello mars                          | /Users/stephan/Desktop/phab-38-blog/.fabfile.yaml |
|   bar                       | Hello from base.yml                 | /Users/stephan/Desktop/phab-38-blog/base.yml      |
|   needs                     |                                     | /Users/stephan/Desktop/phab-38-blog/.fabfile.yaml |
|     needs.0                 | local                               | /Users/stephan/Desktop/phab-38-blog/.fabfile.yaml |
|     needs.1                 | script                              | /Users/stephan/Desktop/phab-38-blog/.fabfile.yaml |
|   type                      | dev                                 | host defaults                                     |
.
.
.

New command `find:property`

Phab 3.8 contains a new command named find:property which provides a visual prompt where the user can start typing the
name of a property they are interested in. Phab supports you by offering properties via autocomplete. As an alternative
you can hit enter to get a list of suggestions. After you found the property you are interested in, hit return, and phab
will display the actual value of that property, its ancestors and from where it got read.

Here's a short walkthrough using the files and their config from above.

docs.phab.io

Enhancements to the database command

There's a new subcommand available db:query where you can run a query against the database of a given configuration
without starting a database-shell and run the query manually.

phab -cmy-host-config db:query "show tables"

It will try to get the database credentials from the configuration and apply them. This command is only implemented for
mysql/mariadb for now.

New command `restic`

Phab 3.7 got support for offsite backups via restic. But it was still a bit cumbersome to interact with the restic
repository for a given configuration using restic alone. That's why phab now has the restic command. It is applying the
configuration and options from the fabfile and you can concentrate on the commands you want to pass to restic. Some
examples:

phab -cmy-host-config restic snapshots
phab -cmy-host-config restic -- snapshots --host-name my-config
phab -cmy-host-config restic -- forget --keep-daily=14 --keep-weekly=4 --keep-monthly=6 --group-by host --prune

Experimental integration with ddev

ddev is a superb tool for managing local development environments and provides similar features as phabalicious. As it
takes a lot of time to maintain a local development stack (like multibasebox) we thought it might make more sense to
embrace existing open-source tools.

As ddev is also using docker and docker-compose under the hood it was very unproblematic to integrate ddev with phabalicious.
Phab will read the ddev configuration from .ddev/config.yaml and provide it under the global property ddev. So it's
very easy to provide a phab configuration for your local ddev instance. Instead of copy-pasting the boilerplate into
every project we store it on a central place and inherit from it in the fabfile:

Store this file in a central place, e.g. in your user-folder or on a remote-server. For demonstration purposes we store
this in the same folder as the fabfile

the ddev.yml-file:

requires: 3.8.0

dockerHosts:
  ddev:
    rootFolder: .
    runLocally: true


hosts:
  ddev:
    additionalNeeds:
      - ddev
    info:
      description: Local ddev instance
      publicUrls:
        - "https://%settings.ddev.name%.ddev.site"
      category:
        id: 01-local
        label: Local development
    executables:
      drush: /var/www/html/vendor/bin/drush

    shellProvider: docker-exec
    composerRootFolder: /var/www/html
    gitRootFolder: /var/www/html
    rootFolder: /var/www/html/web
    backupFolder: /var/www/backups
    docker:
      configuration: ddev
      name: ddev-%settings.ddev.name%-web
      projectFolder: .

the actual .fabfile.yml:

inheritsFrom:
  - ./ddev.yml

hosts:
  ddev:
    # its a drupal installation, so add the drupal-specfic stuff
    adminPass: admin
    replaceSettingsFile: false
    alterSettingsFile: false
    executables:
      drush: /var/www/html/vendor/bin/drush
    needs:
      - git
      - docker
      - drush
      - files

running phab list:hosts will show sth like this for your ddev-project:

❯ phab list:hosts -v

Available configurations for your project
=========================================

Local development
-----------------

 ‣ ddev
   Local ddev instance
   → https://my-ddev-site.ddev.site

You can run any command against the ddev site as usual. For controlling app lifetime please use ddev, e.g. ddev start
or ddev stop

New run contexts for yarn, npm and others

The configs for yarn, npm, composer and laravel changed. The composite property name like yarnBuildCommand is
deprecated, please move the config under a section named yarn. This allows us to add more options for the respective
commands by keeping a structure. Phab will support the old property-names until the next major release, for now you'll
get a friendly reminder.

One of the reasons for this change is the extension of the runContext, which got renamed into context which will adapt
the existing functionality of the script execution contexts. Build commands can now be multiline, but then please
provide the executable-name by yourself:

Old:

hosts:
  test:
    yarnBuildCommand: build:production
    yarnRunContext: docker-host

New:

hosts:
  test:
    yarn:
      buildCommand:
        - yarn build:production
        - yarn build:assets
      context: docker-image
      image: node:16

There are two new contexts available which pigypack on the existing functionality of script execution contexts:

docker-image will execute the yarn build in a docker image (see script execution contexts for configuration options)
docker-image-on-docker-host same as above, but it will be executed on the same instance where docker-commands are executed, usually where your dockerConfig points to.

Smaller enhancements

Passwords are now obfuscated in phabs output.
Update-check is now using a maintained [php
library](https://github.com/consolidation/self-update) and works more reliably. Please that the name of the option for getting a beta-version changed too.
When importing a sql-dump phab freezes the app, and unfreezes it afterwards. For drupal applications the site will be put in maintenance mode and back.

Switch to conventional commits and semi-automated releases

We switched to the conventional commits convention and introduced standard-release to help us creating proper releases.

Where to get it

See the documentation for installation

How to test a beta version of phabalicious in parallel

Stephan Maximilian Huber — Sat, 13 Aug 2022 11:42:00 +0000

Sometimes it would be neat to test if a new beta version of phabalicious works with my local projects, without breaking
my productivity if I encounter problems. Fortunately it is rather safe to have two phab versions installed on your local
computer.

Usually you keep phabalicious up-to-date by running phab self-update. The easiest way to install a beta-version side
by side to the official version are the following commands:

$ curl -L  https://github.com/factorial-io/phabalicious/releases/download/3.8.0-beta.16/phabalicious.phar --output /usr/local/bin/phab38
$ chmod +x /usr/local/bin/phab38
$ phab38 --version
phabalicious 3.8.0-beta.16

Please adapt the version in the url to your likings. After a successfull installation you can update the beta version using

phab38 self-update --preview

And if you want to test if your project is still working with the new beta version, just substitute phab with phab38, e.g.

phab38 -cmbb docker run

If you encounter any problems with a beta or a stable version please create an issue
To remove the beta-version just run rm /usr/local/bin/phab38

Backend Development at Factorial

Niklas Franke — Mon, 28 Feb 2022 11:17:21 +0000

What challenges do we face in backend development at Factorial? And what role does Drupal play in our work as an agency? In our latest video, Shibin, Senior Backend Developer at Factorial, gives an overview of our projects and how we develop digital solutions for our clients.

He also mentions our technology stack we work with and the importance of open-source of us as a company.

Find the clip here:
See Video

Contribution days at Factorial

Niklas Franke — Mon, 27 Dec 2021 08:21:54 +0000

We have an important announcement to make! By the start of 2022 we introduce the contribution days at Factorial. The contribution days will allow the team members to dedicate more time on their open source projects and will be available for every team member.

Open source has always been shaping our corporate identity which is why we decided to take the leap and actively promote it in our team. Read in this article about our connection to open source and what led us to that decision.

Why we encourage open source

At Factorial, the words open source are strongly connected to our daily work. In our projects we most exclusively create our digital products with open source technology, building websites and web applications with Drupal, Laravel, Symfony, Node.js or Vue.js — only to name a few. This is why we are heavily relying on the awesome work, developers from all over the world are dedicating their valuable time to. It is their effort that keeps these technologies alive, updated and safe to use.

Contributions therefore leave a great impact on the system and its community. In our projects we are trying to worship this approach as well by giving something back. This not only happens collaboratively as a team, also many of our team members have their individual projects where they are actively contributing to the open source community.

Some open source projects from our team members

We have a couple of team members that participate actively in the open source community. Our colleague Shibin for instance actively participates in the Decoupled Menu Initiative (Read his article here) in order to improve the developer experience for Drupal acting as a headless CMS.

Besides that there is Michi who created Miyagi, a storybook alternative that allows you to have awesome and really well structured component libraries or living style guides. Its philosophy is to stick as close to the platform technologies as possible and doesn’t rely on many external libraries. It’s a great toolkit for component based frontend development. With clever naming conventions of your css custom properties, you get valuable design tokens such as font-variants, colors, spacings visualized out of the box.

Another example for continuous contribution is our colleague Kristiaan. He picked up his work on his Drupal module Group already 8 years ago. The Group module enables users to create arbitrary collections of web content and handles the access control permissions on those collections. Currently almost 11.500 websites report using this module. In this year, a new release came to life (Read his article here) that brought the additional feature of making Groups fully revisionable through code and the UI. Since the start of Group much has happened and Kristiaan received a wave of appreciation within the community for his work. But during years of development he also stumbled upon something that we think is giving the core idea of open source a negative connotation.

Great power comes with great responsibility

In the previous paragraph you have seen the amount of positive feedback that is passed on in the open source community. But in between all the acknowledgement there are the limitations a passionate developer is facing while dedicating his/her/their time to the numerous requests and bug fixes.

The problem here is, that all of this open source contribution has to be made simultaneously to a full-time employment, because the open source work is mostly not being financially compensated. This means that the developer often squeezes extra work into his/her/their timetable in order to do equal justice to all. And this work doesn’t shrink on a long term perspective, because the more work that is put into the open source project, the louder the calls for requests get. Suddenly, the developer’s passionate project becomes an extra burden in order to keep up with the increased workload. If this goes on and on, it’s hard to maintain creativity and passion in such a high pressure environment.

We think that tech companies that benefit from open source technologies have a responsibility to shape and also support that community. And they should try to enable their employees to participate in it as part of their jobs.

We want to give something back

We at Factorial want to encourage our team members to focus on their contributional work without having to worry about the financial coverage that much. For this reason, from the beginning of 2022, we at Factorial announce the Contribution Days. We give 10 additional days every year to each of our team members to dedicate them to open source contributions. This is not only scoped to our team of developers. We want to encourage everyone, no matter what discipline, to contribute to open source. That could be fixing bugs in an existing open source project, designing a website for an open source project or even helping to organize a meetup or conference. Basically everything that helps the open source community is a great fit.

With this approach we hope to get more of us engaged in open source projects and want to create a supportive environment for our team members in being more creative and passionate about their work. Also we want to highlight the very core of open source — to work together and spend your time on things you like.

Developing and Testing Web Components

Andrew Beng — Thu, 14 Oct 2021 00:50:27 +0000

This blog is a follow up from my previous article "Custom Elements with Vue Reactivity". Here I will be sharing my thoughts on the challenges I faced setting up development and unit testing environments, while not forgetting about accessibility concerns for a Web Components project.

Thinking about Developer Experience

As Vue.js developers, we are spoiled when it comes to developer experience (DX), or “the experience developers have while using or working on your product”. From first-class documentation, to browser extension based or standalone Vue developer tools, to opinionated packages for routing, state management and unit testing, Vue’s ecosystem has always been developer centric, and newcomer friendly. Good DX is therefore a key value software project maintainers should work towards for long-term sustainability of their projects or their developer community.

When experimenting with Custom Elements in developing vue-uhtml, the lack of (or at least the lack of documentation of) developer tooling with decent DX became quickly apparent. To date, there is now default or opinionated out-of-the-box solution for web developers to spin up a basic development server to serve vanilla HTML, CSS and JavaScript - the underlying web technologies Custom Elements builds upon. I chose to scope the developer experience considerations for the vue-uhtml project to three areas:

How might developers use vue-uhtml to develop a UI library
How might developers unit test components built with vue-uhtml
How might developers be aware of accessibility issues when developing with vue-uhtml

A dev environment for Custom Elements projects

Storybook is a popular and easy-to-use open source tool for building UI components in isolation. Given my previous experience in using Storybook for Vue based projects, this was a natural option for UI development with vue-uhtml. Storybook’s Web Components flavour made this decision an even easier one since this is officially supported and well documented. One possible drawback when using Storybook for Web Components is the use of the lit-html templating utility to create “stories” for your components. The lit-html project is incidentally the library Evan You chose to implement his own Custom Elements project with. In the case of this project, having to implement components in a slightly different uhtml syntax and “stories” in the lit-html syntax is objectively a negative developer experience, and has to be considered further for a wider vue-uhtml developer community.

A major hurdle to overcome when developing Custom Elements is an approach for implementing styles and CSS via the encapsulated Shadow DOM, especially when also using CSS pre and post processors. This issue is usually solved during the build process when tools like Webpack or Rollup orchestrate CSS transformations before bundling and injecting processed styles in the right place. Front-end framework CLI tools like vue-cli-service, Vite or create-react-app abstract much of the underlying processing and building for both development and production environments. For example, most Vue developers would not need to be concerned with how a Vue single file component gets compiled by Webpack or Vite and served on a local port when yarn serve is run. This is great DX, but probably not something that would be easily achievable for vue-uhtml development in the short term.

Putting the pieces together, these were the steps I took to set up a Storybook based development environment with decent DX to build UI components with vue-uhtml:

Configure a bare bones Rollup project to process vue-uhtml defined Custom Elements for both development and production
Configure Rollup to watch the src directory to compile the components to a dev directory
Configure Storybook for Web Components and write component stories using the rolled-up output component definitions in the dev directory (rather than src)
Run Rollup and Storybook concurrently via a dev script

// UiCheckBox.stories.js
import { html } from "lit-html";
import { defineUiCheckBox } from "../../dev/index.esm";

defineUiCheckBox();

export default {
  title: "Components/UiCheckBox",
};

const Template = () => html`<ui-check-box></ui-check-box>`;

export const Default = Template.bind({});

The trial and error in setting up these steps could in the future be the basis for vue-uhtml’s own CLI, or to extend or use Vite for a similar purpose.

Unit testing Custom Elements

The next consideration I addressed was being able to easily write and run unit tests for vue-uhtml components. Having previously talked about a unit testing approach for Vue.js components, I was keen to apply the principle of “writing tests that assert your component’s public interface”. Before I could even think about writing component tests, I had to pick the most appropriate and well supported tooling. Vue’s documentation on testing and own vue-test-utils package makes this choice a foregone conclusion with Jest as a comprehensive test framework, and using vue-test-util’s wrapper based API to mount components in an isolated jsdom environment. While jsdom has provided a Custom Elements implementation since version 16, other Web Components APIs including Shadow DOM are not supported or reliable enough to be useful.

Since Custom Elements is a browser based web technology, a common approach to work around jsdom’s limitations is to consider using Puppeteer to run tests on Custom Elements rendered in real browsers. However, in practice this usually isn’t the most practical solution as “boilerplate” code is required to navigate to the components on a served HTML page.

To improve DX and streamline the unit testing approach for Custom Elements, the folks at Open Web Components have provided an opinionated testing package aptly called @open-wc/testing that “combines and configures testing libraries to minimize the amount of ceremony required when writing tests”. While not having a choice of test runner or assertion library (@open-wc/testing uses Mocha and Chai respectively with Puppeteer) may seem restrictive, the positive trade-off is clear documentation and concise examples to help get up and running writing component tests.

Potential gotcha: `shadowRoot.mode`

The encapsulation of Custom Element features is aided by the ability to set a component’s shadowRoot mode to ”closed”, preventing the shadow root's internal features being accessible from JavaScript. This is a feature that is set to “closed” by default when building components with vue-uhtml. This has potential “gotcha” implication in preventing test scripts from asserting the components’ internal features. To prevent falling into this trap, components based on Custom Element should easily allow developers to be defined with an ”open” shadow root mode when used in tests.

The example below outlines tests for a custom checkbox component which:

Asserts that the initial checked value is false
Asserts that the checked value is true if its attribute is passed
Asserts that the checked value is true after the input is clicked

import { html, fixture, expect, elementUpdated } from "@open-wc/testing";

import { defineUiCheckBox } from "../../dist/index.esm";
defineUiCheckBox({ isTest: true });

describe("UiCheckBox", () => {
  it("has a default checked value which is falsy", async () => {
    const el = await fixture(html` <ui-check-box></ui-check-box> `);

    expect(el.checked).to.not.be.ok;
  });

  it("has a checked of true when the 'checked' attribute is passed", async () => {
    const el = await fixture(html` <ui-check-box checked></ui-check-box> `);

    expect(el.checked).to.equal(true);
  });

  it("has checked value after click", async () => {
    const el = await fixture(html` <ui-check-box>Checkbox</ui-check-box> `);

    expect(el.checked).to.not.be.ok;

    el.shadowRoot.querySelector("input").click();

    await elementUpdated(el);

    expect(el.checked).to.be.ok;
  });
});

Developing with `a11y` in mind

Web accessibility (a11y) has historically been an area overlooked by developers and designers alike, often seen as more of an art than precise science. While there is no single tool or methodology that solves all a11y concerns for web development, significant progress in tooling has made it possible to integrate Web Content Accessibility Guidelines (WCAGs) into development workflows. Although the use of such developer tools does not solve the actual task of authoring accessible websites and apps, they do help developers become more aware of the a11y topic during development rather than after. One such tool at the forefront of this drive to assist developers in developing with a11y is axe, which provides an open-source accessibility rule set for automated accessibility validation. The axe rule set can in turn be used in a11y validation plugins in other developer tools. I was able to easily integrate an axe based a11y plugin for Chai with @open-wc/testing into my vue-uhtml components project.

The axe plugin for Chai allows developers to automatically run a11y validation as part of their TDD or BDD workflow.

await expect(el).to.be.accessible();

Take-aways

Thinking about developer experience in the context of developing a Custom Elements based project has been a lot like thinking about user experience when developing front-end websites and applications. Instead of a visual user interface, a tool/library/framework’s API is the end user’s (in this case developer’s) medium for achieving their tasks. This small exercise in DX has made me appreciate the thoughtful contributions open source maintainers make in keeping their tools and documentation easy to use for the wider developer community.

Links

Custom Elements with Vue Reactivity

Andrew Beng — Thu, 08 Jul 2021 08:22:31 +0000

The 13th Hamburg Vue.js Meetup was held last week, this time as an online live-stream due to the ongoing COVID-19 restrictions. I was pleased to represent Factorial to share a talk on some insights on a small experiment in building Custom Elements with Vue 3.x’s standalone Reactivity module. Having previously worked with Vue’s own Custom Elements build option, I was keen to re-explore this topic with standalone Reactivity, also spurred on by Evan You’s ~70 lines-of-code experiment. My own question was, “could it really be that simple?”

Vue 3.x Reactivity

Vue’s Reactive utility (previously known as Vue.observable) has been heavily overhauled since the release of Vue 3 late in 2020. Its dependency to ES6 Proxy makes observing state changes a breeze for developers, but also means that Vue 3 drops support for Internet Explorer 11.

Custom Elements

Custom Elements is a foundational Web Components which allows developers to create and extend HTML tags. The main goal of the Custom Elements API is in creating reusable components (an objective shared with front-end libraries and frameworks like Vue, React, or Angular), using web standards: HTML, CSS and JavaScript. In using web standards, the biggest advantage of using Custom Elements is their easy interoperability in other framework specific projects, e.g. sharing the same Custom Elements across Vue or React projects.

In practice, creating vanilla Custom Elements often involves writing lots of boilerplate code, especially when setting up reactive properties and observed attributes. This is something which is solved in some of the wide array of Custom Elements libraries and frameworks available. Addressing the issue of verbose boilerplate code is also an area where standalone Reactivity shines.

The “vue-micro” Experiment

My experiment in creating a framework to build Custom Elements borrows from Vue creator Evan You’s own proof of concept called vue-lit. The goals of my vue-uhtml (“vue-micro”) experiment were to:

Add props validation
Add a <slot> interface
Implement some form of test coverage

The pseudo code below provides an overview of how the Custom Elements API is used to emulate the rendering and reactive features seen in Vue components.

export default ({ name, setup, props }) => {
  customElements.define(
    name,
    class extends HTMLElement {
      static get observedAttributes() {
        // Return a list of observed attribute names
      }

      constructor() {
        // 1. Scaffold reactive props
        // 2. Scaffold slots as reactive object
        // 3. Apply effect to render the template + run hooks
      }

      connectedCallback() {
        // 1. Run beforeMount hook
        // 2. Render template + invoke setup()
        // 3. Run mounted hook
        // 4. Bind template slots to reactive object
        // 5. Validate props
      }

      disconnectedCallback() {
        // Run unmounted hook
      }

      attributeChangedCallback() {
        // Parse, validate and update reactive props
      }
    }
  );
}

[Pseudo code structure of vue-uhml - JavaScript]
View the actual code here.

Here’s an example of vue-uhtml in action combining reactive re-rendering on user input, props validation, and using a named <slot>.

I spent some time researching how Custom Elements could be test-automated. The community driven Open Web Components initiative provides a set of defaults, recommendations and tools to help facilitate web components projects. The @open-wc/testing package combines and configures testing libraries to quickly get up to speed writing tests for Custom Elements. The vue-uhtml repository includes tests for a Custom Element built with vue-uhtml covering lifecycle hooks, user input and props interfaces.

Take-aways and possible future

To conclude the talk, I shared my top three take-aways from this experiment with the Vue.js Hamburg:

Standalone Vue Reactivity is pretty awesome
Custom Elements are not scary
More developers should also get out there and experiment

My learning experience through this process of experimenting with community driven open source software far outweighed the extent of checking off the original goals I had set out. I was encouraged on this point that the second talk of the evening by Thomas Jacob from sum.cumo (“VueGround: Ein Design-Tool und Playground für Vuetify, in Vuetify”) was also in the spirit of experimentation.

Writing user centric documentation and more comprehensive test coverage for vue-uhtml are two areas to focus on before vue-uhtml to be “production ready”. Whether vue-uhtml will be added to the wide selection of Custom Elements frameworks already available remains a question for the wider developer community to engage with.

Many thanks to Vue.js Hamburg and Joe Ray Gregory for organising this online Meetup, and to sum.cumo for the smooth hosting of the live-stream on YouTube. We are indeed looking forward to the day when in-person Vue.js Hamburg meetups will be possible again.

From design to code

Michael Großklaus — Tue, 13 Apr 2021 07:49:40 +0000

Since 2020, we at Factorial do not only offer web development, but also conception and design for all kinds of web projects. And while in the past designing and developing websites has usually been a quite separate process, there are nowadays powerful tools for cooperation between designers and developers. At Factorial we try to make use of these tools as much as possible.

Designing in Figma

Our designers work with Figma, a web-based design tool developed for easy collaboration with developers. We will show later how we actually make use of that, but for now let us have a look at how we structure the projects.

Usually we create five so called “Pages” in Figma:

Design Tokens
Elements
Patterns
Template components
Templates

Design Tokens

Design tokens are a set of styles — colors, typography, size and effect variables that are used across the product — to create a consistent and simple design language.

On the Design Tokens page, we create four different art boards: Colors, Typography, Spacings, Other

Colors can contain colors for typography but also decorational colors. It is important for us to separate these two to make sure that certain colors should only be used for certain things. E.g. a light grey might be good for background or an outline, but not good for typography as the contrast ratio could fail, especially for visually impaired users.

Spacings contain a list of pixel based spacing values (which will later be converted to rem in CSS), usually starting at 4 and containing not more than 8-10 values.

Typography lists all different types of text styles: headlines, copy, highlighted text, links and so on.

On Other we define values for elevation, borders, radiuses or certain effect styles needed for i.e. hover effects or overlays.

Elements, Patterns, Template Components and Templates

The pages Elements, Patterns, Template Components and Templates are where the actual designs are located.

On Elements we have small components which can be reused everywhere. These are usually components like buttons, icons, form elements, images, etc..

Patterns are combinations of elements, but not only. They are rather complex components like an image gallery, rich text, a slide show and so on. These components can later be picked by the editors of a CMS to compose the content of a website, e.g. using Drupal’s Layout Builder.

Template components are the single parts of a template: header, footer, navigation, search results, sidebar etc.. These elements can not be picked by editors, but are instead a fixed part of templates.

Templates bring everything together: They connect template components and patterns and represent completes pages like a homepage, product page, search results, etc..

Importing design tokens via Figma API

When naming pages, art boards and tokens in Figma, it is very important that we follow a certain structure and naming convention. Not only does that make communication and reusability easier, it also allows us to use the Figma API to import our design tokens and components directly into our projects.

Our frontend stack, which is part of every new project, contains a small script, which lets us do exactly that. When executing it, it will use the Figma API to connect to our Figma file, receive a JSON response containing all the necessary information about the designs and then create

a tokens.css file, which contains CSS custom properties based on the Design Tokens page in our figma file,
empty components based on the other four pages.

The custom properties are named accordingly to the design tokens in the Figma file. This makes sure that designers and developers talk about the same things and it simply makes it easier to remember how things are named. Since this file is auto-generated, it should never be changed manually. As soon as we run the import again, this file would be overwritten.

For elements, patterns, template components and templates, the script creates empty components in the same hierarchy. If the Figma file e.g. contains a button component on the Elements artboard, it would create

elements
└── button
    ├── button.css
    ├── button.twig
    ├── mocks.yaml
    └── schema.yaml

It would only do that if this component does not exist yet to avoid overwriting components, which have already been implemented.

While the button.css and button.twig (twig is template language of our choice) are part of the actual component, the mocks.yaml and schema.yaml are important for collaboration with backend developers and for our component library.

Developing in miyagi

After having used Pattern Lab for many years, it met our requirements as a component library less and less. It is a proven, well-working tool, but it started feeling too heavy and too slow for us. We also had increasing needs, which our component library should fulfil and Pattern Lab was simply not able to do that. After evaluating lots of different tools and not being able to find just one tool which would be able to deliver everything we need, I ended up creating a tool myself to serve that purpose. It is called miyagi.

miyagi is a node module, using an express server and can basically fit to any project structure you have. You can name your folders and components any way you want, nest them as deep as you want, use (almost) any kind of JavaScript templating language and all it needs in your project is one configuration file (it actually even works without a configuration file by trying to guess your template language, but you need to follow a certain naming convention for your folders and components then). This allows us to use it in different kinds of projects while keeping the project structure completely independent from our component library. If we ever want to use a different one, all we need to do is remove the configuration file.

Design tokens

When you open the start page of a miyagi instance, you will get a representation of our design tokens: miyagi is able to parse our CSS files, look for custom properties with a certain naming (which we get out of the box thanks to our token importer) and create a nice overview of all design tokens we have in a project.

Customer theme

miyagi can also be styled in the CI of our customers: fonts, colors, a logo and basically any CSS can be added to give the customer the feeling that it is their component library.

The schema files

The schema files are JSON schema files. We use them to agree on a certain data structure for a component, to make sure that the provided data by a backend service actually fits to that component. But they also allow our designers to come up with certain restrictions, e.g. a given text should only be 200 characters long etc..

While these schema files are independent from a component library, they are still used by miyagi to validate the mock data: If the given mock data for a component does not fit to the given JSON schema, it will render an error.

The mock files

One aspect of component libraries is usually that they allow encapsulated and indepenent development of components. This means that frontend developers can build a component without having to wait for a backend service, which provides them data or an environment to render this component.
To do that in miyagi, we can create mock files to provide dummy data for our components. This can be static using yaml or json, but you can also use JavaScript files, which asynchronously export data coming from some API, for example. That way we can have many different variants of a component to make sure that the components always work, no matter how the data which is passed to the component looks like.

Based on these mock files, miyagi creates a separate view for every variant. We use these views also for our visual regression tests.

Testing for visual regressions using our component library

To make sure that we do not accidentally create visual regressions, we use BackstopJS to test our components (including all elements, patterns, template components and templates) for exactly that.

The way this works is that when creating a pull request in our git repository, we first create a static build of our component library (which will later be deployed to a dedicated instance, so everyone can have access to that: designers, developers, project managers, the client, …) and then use these static build files to compare them with the previous ones (which are checked in to the git repository).
That means we have a direct coupling between our component library and our visual regression tests and are not depending on some third party services: there won’t be any downtime and nothing leaves our servers.

Starting projects with the Frontend Starter Kit

Last but not least, we tried to make things even easier, even more consistent and therefore even better and stable.

Since websites do quite often consist out of the same (or at least very similar) components, we came up with the Frontend Starter Kit, which is basically made of all of the above:

a Figma file which contains accessible colors, typography, components like form elements and so on
web components for form elements and other recurring components, which are published as node modules
a Drupal theme providing form elements and other types of components
all developed and tested for visual regressions using miyagi

This Frontend Starter Kit works for many different types of projects and since we publish the components as node modules, we can even use them in Vue projects.

Overall this allows us to have a standardized, well-proven and consistent base for all our projects, avoiding the “stupid” work which every project contains and letting us concentrate on the rest.

Frontend Development at Factorial

Niklas Franke — Thu, 28 Jan 2021 14:47:16 +0000

What does a frontend developer do at Factorial? Our colleague Julian shares some insights about the Frontend Developer role in our team.
See the full video: https://bit.ly/3aaCGcZ

About the importance of including DevOps in your team

Stephan Maximilian Huber — Thu, 17 Dec 2020 16:17:42 +0000

Developers working on client projects are taking care of numerous tasks. When you think the list gets shorter, new things are added at the bottom. What you can do is provide an infrastructure that lets them tackle their issues. But this doesn’t include only the administrative side but also the technical requirements for the developers to work properly. What’s missing is someone who is familiar with the IT area of the developers and has the capacity to assist in operative processes aside from the usual management. This is where the DevOps enter the field.

The DevOps work to hold the development team’s back. They appear as the merge between operations and development, supporting the team by managing the software and applications, deployment of tools in order to simplify procedures and smoothen the development process. With his work the DevOps face delays and other performance interferences by reducing downtimes and system failures. The use of DevOps in your team not only assures quality and an optimized workflow, you also stick to the latest development trends and keep yourself and your team up to date.

What skill set do the DevOps need?

Let’s start with the most obvious one: The development skills. The differentiation element of the DevOps in comparison to an administrative manager are their skills regarding programming and scripting. This includes various programming languages, open source technologies and tools as well as knowledge in server systems and security concepts. The DevOps prove their expertise for the position through their understanding of source control systems, infrastructure automation tools, cloud services and testing skills. Aside from the technological competences required in this area, the DevOps need to combine this with a set of soft skills that they can come up with.

As they stand for the binding component between different teams an excellent communication is indispensable. Bearing in mind the amount of possible issues the DevOps need to solve, which is a challenge for itself, and to keep a cool head and show empathy and integrity is not easy. Last but not least the job requires more than any other the willingness to educate yourself. The digital environment is in a continuous change and so are the skills the DevOps have to maintain in order to stay an expert in their area. Being well-informed about new technologies, systems and procedures will prepare the DevOps for the never ending wave of issues and errors they need to solve to support their team.

How do we implement the DevOps role at Factorial?

We at Factorial divide the tasks of the development operations on various shoulders. In this case we not only have specific members of the team dealing with specific tasks, we also use administrative development programs in order to automate workflows. We established a way to centralise logging and monitoring and also administer our zoo of hosted applications like Jira, Confluence and Mattermost to constantly improve our corporate infrastructure. With this we work on new ways of streamlining our processes and think about new features like rapid rollouts of dev instances.

In addition to that we enhance and develop our local dev stack based on MultiBaseBox. Our devs are using docker for spinning up the needed dependencies for their projects. We are using MultiBaseBox and phabalicious for local development. The underlying haproxy container with automatic configuration is also used as an easy way to spin up remote dev instances, so clients can test new features. Our team is constantly enhancing and extending these tools.

phabalicious

By using phabalicious our devs are equipped with all necessary and project related information within one single configuration file. With this program our devs can connect to the actual app installation, be it locally installed, behind a ssh-jump-host or part of a kubernetes cluster and can execute common, every-day tasks as getting a database dump, deploying a new version of the application or just get a shell on that particular instance. Recently our engineers added support for kubernetes. It’s actively maintained by our team, and adapted to the ever changing needs of our developers and clients, while trying to be as open as possible.

kubernetes

Our devs can rely on kubernetes as a valuable tool to administer and create definition files for our clusters and the clients’ clusters. They can bring Drupal-, Laravel- or Node-based websites and applications into a kubernetes based cluster and monitor the applications over time.

GitLab & docker

As passionate developers we work with GitLab as our main code repository and make full use of its strong integration capabilities provided by Pipelines. In addition to that we use docker to provide the best working environment for our developers all across the globe.

Wrap-up

The DevOps appear as the perfect match to your development team. In fact, as we at Factorial see it, the development team isn’t complete without someone uniting the understanding of development processes and programs with the administrative knowledge that ties all together. The true value this role can bring to your business, is not only from an economical standpoint but also in terms of stress reduction and process optimization. If you haven’t thought working with this role yet, you might be surprised about the value it can contribute to your company.