Fully typed forms based on API schema with react-hook-form, openapi-typescript and yup validation

Hello everyone, my name is Dmitrii Pashkevich and I’m a Frontend Developer at Quadcode. This article will explain to you the approach to creating fully typed forms in React applications using react-hook-form, openapi-typescript and the yup validation. This method relies on an API schema to ensure that the form data exactly matches with the types from the backend API schema, simplifying development and reducing errors in the process. Whether you are a Frontend or a Full-stack Engineer looking to improve form reliability, I hope you find this material useful. Enjoy reading it!

About

Let’s consider an example of creating the form with POST request and a basic entity “Offer” consisting of 4 fields:

• name — full name of the “Offer”. Field: string; mandatory; maximum length 1024 characters;
• short_name — short name of the “Offer”. Field: string; mandatory; maximum length 1024 characters;
• advertiser_id — advertiser id to which the “Offer” belongs. Field: number; mandatory for filling;
• model — alias of the model on which the “Offer” works. Field: string; mandatory; maximum length 1024 characters.

Project preparation

Let’s create a basic React project using the generator from Vite with the directory name fully-typed-form.

npm create vite@latest

The command will result in a directory containing a simple React application. To keep things simple, let’s assume that the server API will be described as a yaml file containing a description of the Open API schema, which allows you to send a request to create an “Offer” entity.

Let’s start a file describing the Open API schema — fully-typed-form/server/offers.openapi.yaml.

openapi: 3.1.0
info:
  title: Example API for article
  description: Article "Fully typed forms based on API schema with react-hook-form,  openapi-typescript and yup validation"
  version: 1.0.0
servers:
  - url: 'https'
paths:
  /api/offers:
    post:
      summary: Create offer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferPostBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferId'
components:
  schemas:
    OfferPostBody:
      required:
        - name
        - short_name
        - advertiser_id
        - model
      properties:
        name:
          description: Full offer name
          type: string
          maxLength: 1024
          x-oapi-codegen-extra-tags:
            validate: "required,notBlank,lte=1024"
        short_name:
          description: Short offer name
          type: string
          maxLength: 1024
          x-oapi-codegen-extra-tags:
            validate: "required,notBlank,lte=1024"
        advertiser_id:
          description: Id of the advertiser
          type: integer
          x-oapi-codegen-extra-tags:
            validate: "required"
        model:
          description: Model alias
          type: string
          x-oapi-codegen-extra-tags:
            validate: "required,notBlank,lte=1024"

    OfferId:
      type: object
      properties:
        id:
          type: string
          description: Id of the offer

In order to generate an API-based schema, let’s use the openapi-typescript library, which is a tool designed to generate TypeScript types based on OpenAPI specifications. It helps to automatically generate data types to work with the API, which greatly simplifies the integration process and increases code reliability.

Let’s execute the type generation command for the above API schema.

npx openapi-typescript server/offers.openapi.yaml -o src/shared/types/api/offers.types.generated.ts --make-paths-enum --root-types-no-schema-prefix --root-types --path-params-as-types --alphabetize

The output is a generated file src/shared/types/api/offers.types.generated.ts containing types corresponding to the scheme described above.

/**
* This file was auto-generated by openapi-typescript.
* Do not make direct changes to the file.
*/

export interface paths {
   "/api/offers": {
       parameters: {
           query?: never;
           header?: never;
           path?: never;
           cookie?: never;
       };
       get?: never;
       put?: never;
       /** Create offer */
       post: {
           parameters: {
               query?: never;
               header?: never;
               path?: never;
               cookie?: never;
           };
           requestBody: {
               content: {
                   "application/json": components["schemas"]["OfferPostBody"];
               };
           };
           responses: {
               /** @description Created */
               201: {
                   headers: {
                       [name: string]: unknown;
                   };
                   content: {
                       "application/json": components["schemas"]["OfferId"];
                   };
               };
           };
       };
       delete?: never;
       options?: never;
       head?: never;
       patch?: never;
       trace?: never;
   };
}
export type webhooks = Record<string, never>;
export interface components {
   schemas: {
       OfferId: {
           /** @description Id of the offer */
           id?: string;
       };
       OfferPostBody: {
           /** @description Id of the advertiser */
           advertiser_id: number;
           /** @description Model alias */
           model: string;
           /** @description Full offer name */
           name: string;
           /** @description Short offer name */
           short_name: string;
       };
   };
   responses: never;
   parameters: never;
   requestBodies: never;
   headers: never;
   pathItems: never;
}
export type OfferId = components['schemas']['OfferId'];
export type OfferPostBody = components['schemas']['OfferPostBody'];
export type $defs = Record<string, never>;
export type operations = Record<string, never>;
export enum ApiPaths {
   PostApiOffers = "/api/offers"
}

The example project will be described using FSD (Feature-Sliced Design), so if you don’t want to read about prep work, auxiliary utilities, types and components, you can go straight to the Widgets layer (OfferFormCreate) and skip the description of sections related to shared and features layer.

Next, to implement the form we need to install the following modules.

npm install react-hook-form @hookform/resolvers yup

We’ll also install and connect Mantine UI components so to avoid writing unnecessary styles.

npm install @mantine/core @mantine/hooks
npm install --save-dev postcss postcss-preset-mantine postcss-simple-vars

Also install and connect Tanstack React Query to work with API requests.

npm install @tanstack/react-query

The configuration and connection of Mantine, Tanstack React Query can be found in the file: src/App.tsx.

Shared layer

Located in src/shared and will contain helper utilities, types, API requests, etc.

API requests

The src/shared/api/offers.api.ts contains an emulation of the request to create an offerer.

import { OfferPostBody } from '../types/api/offers.types.generated.ts'

export const apiOfferPost = async (values: OfferPostBody) => {
 await new Promise((resolve) => setTimeout(resolve, 1000))

 console.info(values)
}

CreateEnumObject utility

To simplify the work with typing and description of form fields, let’s create an auxiliary utility to turn Union type into an object: src/shared/types/utils/createEnumObject.ts.

export const createEnumObject = <T extends string>(o: { [P in T]: P }) => {   return o }

This utility will be useful for following the uniform naming of form fields among the project files.

FormSelect component

This is an auxiliary wrapper component over Mantine Select that will allow this component to be connected to a react-hook-form by using useController. This is necessary because it is not possible to use form.register to control a field because the type for onChange (a component parameter) is different.

// react-hook-form onChange
export type ChangeHandler = (event: {
   target: any;
   type?: any;
}) => Promise<void | boolean>;

// VS

// Mantine Select onChange
onChange?: (value: string | null, option: ComboboxItem) => void;

The full code of the component can be found in the file: src/shared/components/FormSelect.

import { type FieldValues, useController } from 'react-hook-form'

import { Select as MantineSelect } from '@mantine/core'

import { FormSelectPropertiesType } from './FormSelect.types.ts'

export const FormSelect = <T extends FieldValues>({
 name,
 control,
 defaultValue,
 onChange,
 rules,
 shouldUnregister,
 ...properties
}: FormSelectPropertiesType<T>) => {
 const {
   field: { onChange: fieldOnChange, value, ...field },
   fieldState,
 } = useController<T>({
   name,
   control,
   defaultValue,
   rules,
   shouldUnregister,
 })

 return (
   <MantineSelect
     onChange={(value, option) => {
       fieldOnChange(value)
       onChange?.(value, option)
     }}
     error={fieldState.error?.message}
     value={value}
     {...field}
     {...properties}
   />
 )
}

Features layer

Because the form will contain interactive elements for working with advertisers and models, let’s place them in the features layer.

AdvertiserSelect component

The full code can be found in the file: src/features/AdvertiserSelect.

import type { AdvertiserSelectPropertiesInterface } from './AdvertiserSelect.types.ts'

import { FormSelect } from '../../shared/components/FormSelect/FormSelect.tsx'
import { ADVERTISERS_LIST } from './base/constant.ts'

export const AdvertiserSelect = ({ name, form, ...rest }: AdvertiserSelectPropertiesInterface) => (
 <FormSelect name={name} control={form.control} data={ADVERTISERS_LIST} required searchable {...rest} />
)

ModelSelect component

The full code can be found in the file: src/features/ModelSelect.

import type { ModelSelectPropertiesInterface } from './ModelSelect.types.ts'

import { FormSelect } from '../../shared/components/FormSelect/FormSelect.tsx'
import { MODELS_LIST } from './base/constant.ts'

export const ModelSelect = ({ name, form, ...rest }: ModelSelectPropertiesInterface) => (
 <FormSelect name={name} control={form.control} data={MODELS_LIST} required searchable {...rest} />
)

Widgets layer (OfferFormCreate)

Next, let’s move on to the main part of the article — organizing a typed form using react-hook-form and validation via yup.

On this layer, let’s create a directory that will contain the form widget for creating an offerer: src/widgets/offers/OfferFormCreate.

The form widget will consist of:

• description of field constants based on the type obtained from the API;
• description of labels and placeholders objects for form fields;
• description of validation scheme;
• a hook for controlling the form;
• form component.

Field object and validation scheme

In order to describe the typed scheme for our form, let’s create a file: src/widgets/offers/OfferFormCreate/base/constants.ts.

The following code comments describe the what and why.

import * as yup from 'yup'

import { OfferPostBody } from '../../../../shared/types/api/offers.types.generated.ts'
import { createEnumObject } from '../../../../shared/types/utils/createEnumObject.ts'


// Constants for yup schema validation
const OFFER_NAME_MAX_LENGTH = 1024
const OFFER_SHORT_NAME_MAX_LENGTH = 1024


// This object contains all fields from OfferPostBody type keys.
// This object created by createEnumObject
// After that action we can use OFFER_CREATE_FORM_FIELDS in all places where we need to use filed names
export const OFFER_CREATE_FORM_FIELDS = createEnumObject<keyof OfferPostBody>({
 advertiser_id: 'advertiser_id',
 name: 'name',
 short_name: 'short_name',
 model: 'model',
})

// Labels mapped to form fields
export const OFFER_CREATE_FORM_FIELDS_LABEL: Record<keyof typeof OFFER_CREATE_FORM_FIELDS, string> = {
 [OFFER_CREATE_FORM_FIELDS.advertiser_id]: 'Advertiser',
 [OFFER_CREATE_FORM_FIELDS.name]: 'Name',
 [OFFER_CREATE_FORM_FIELDS.short_name]: 'Short name',
 [OFFER_CREATE_FORM_FIELDS.model]: 'Model',
}

// Placeholders mapped to form fields
export const OFFER_CREATE_FORM_FIELDS_PLACEHOLDER: Record<keyof typeof OFFER_CREATE_FORM_FIELDS, string> = {
 [OFFER_CREATE_FORM_FIELDS.advertiser_id]: 'Select advertiser',
 [OFFER_CREATE_FORM_FIELDS.name]: 'Type name',
 [OFFER_CREATE_FORM_FIELDS.short_name]: 'Type short name',
 [OFFER_CREATE_FORM_FIELDS.model]: 'Select model',
}

// This is a yup schema. It describes validation options for each field in OfferPostBody
export const OFFER_CREATE_FORM_VALIDATION_SCHEMA: yup.ObjectSchema<OfferPostBody> = yup.object({
 [OFFER_CREATE_FORM_FIELDS.advertiser_id]: yup
   .number()
   .required()
   .nonNullable()
   .label(OFFER_CREATE_FORM_FIELDS_LABEL[OFFER_CREATE_FORM_FIELDS.advertiser_id]),
 [OFFER_CREATE_FORM_FIELDS.name]: yup
   .string()
   .required()
   .nonNullable()
   .max(OFFER_NAME_MAX_LENGTH)
   .label(OFFER_CREATE_FORM_FIELDS_LABEL[OFFER_CREATE_FORM_FIELDS.name]),
 [OFFER_CREATE_FORM_FIELDS.short_name]: yup
   .string()
   .required()
   .nonNullable()
   .max(OFFER_SHORT_NAME_MAX_LENGTH)
   .label(OFFER_CREATE_FORM_FIELDS_LABEL[OFFER_CREATE_FORM_FIELDS.short_name]),
 [OFFER_CREATE_FORM_FIELDS.model]: yup.string().required().nonNullable().label(OFFER_CREATE_FORM_FIELDS_LABEL[OFFER_CREATE_FORM_FIELDS.model]),
})

Hook for working with the form

Next, create a form via react-hook-form and connect the validation scheme described above to it. In order to isolate the work with our form we create a hook: src/widgets/offers/OfferFormCreate/base/hooks/useOfferFormCreate.ts.

Further in the comments to the code, the what and why are described.

import { useMutation } from '@tanstack/react-query'
import { useForm } from 'react-hook-form'

import { yupResolver } from '@hookform/resolvers/yup'
import * as yup from 'yup'

import { apiOfferPost } from '../../../../../shared/api/offers.api.ts'
import { OFFER_CREATE_FORM_FIELDS, OFFER_CREATE_FORM_VALIDATION_SCHEMA } from '../constants.ts'

// yup.InferType is a utility from the Yup library used to extract a TypeScript type from a validation schema.
// It allows you to automatically generate data types based on a Yup schema, helping to avoid code duplication and mismatches between types.
type OfferFormCreateSchemaType = yup.InferType<typeof OFFER_CREATE_FORM_VALIDATION_SCHEMA>

// This hook is used to create a form for creating a new offer
export const useOfferFormCreate = () => {
  // It's a mutation hook from the @tanstack/react-query library. It's handle API request to create new offer
  const { isPending, mutate } = useMutation({
    mutationFn: apiOfferPost,
  })

  // This hook is used to create a form for creating a new offer and handle fields
  // This hook is typed with OfferFormCreateSchemaType.
  // This hook used a validation schema to validate fields (resolver).
  const form = useForm<OfferFormCreateSchemaType>({
    resolver: yupResolver(OFFER_CREATE_FORM_VALIDATION_SCHEMA),
  })

  // This function is used to handle form submit
  const handleSubmit = (values: OfferFormCreateSchemaType) => {
    mutate(values)
  }

  // This function is used to get error message for each field
  const getFieldErrorMessage = (fieldName: keyof typeof OFFER_CREATE_FORM_FIELDS) => form.formState.errors[fieldName]?.message?.toString()

  return {
    form,
    getFieldErrorMessage,
    handleSubmit,
    isPending, // This property is used to check if the API request is pending
  }
}

Form

Now all that is left is to implement the form description using the above hook: useOfferFormCreate. Further in the comments to the code, it is described what and why.

import { Button, Stack, TextInput } from '@mantine/core'

import { AdvertiserSelect } from '../../../features/AdvertiserSelect'
import { ModelSelect } from '../../../features/ModelSelect'
import { OFFER_CREATE_FORM_FIELDS, OFFER_CREATE_FORM_FIELDS_LABEL, OFFER_CREATE_FORM_FIELDS_PLACEHOLDER } from './base/constants.ts'
import { useOfferFormCreate } from './base/hooks/useOfferFormCreate.ts'

// This component is used to create a form for creating a new offer
export const OfferFormCreate = () => {
 // This hook is used to get form instance and other helpers
 const { form, getFieldErrorMessage, handleSubmit, isPending } = useOfferFormCreate()

 return (
   <form noValidate onSubmit={form.handleSubmit(handleSubmit)}>
     <Stack>
       {/* Offer name */}
       <TextInput
         label={OFFER_CREATE_FORM_FIELDS_LABEL.name}
         error={getFieldErrorMessage(OFFER_CREATE_FORM_FIELDS.name)}
         placeholder={OFFER_CREATE_FORM_FIELDS_PLACEHOLDER.name}
         required
         {...form.register(OFFER_CREATE_FORM_FIELDS.name)}
       />

       {/* Offer short name */}
       <TextInput
         label={OFFER_CREATE_FORM_FIELDS_LABEL.short_name}
         error={getFieldErrorMessage(OFFER_CREATE_FORM_FIELDS.short_name)}
         placeholder={OFFER_CREATE_FORM_FIELDS_PLACEHOLDER.short_name}
         required
         {...form.register(OFFER_CREATE_FORM_FIELDS.short_name)}
       />

       {/* Offer advertiser */}
       <AdvertiserSelect
         label={OFFER_CREATE_FORM_FIELDS_LABEL.advertiser_id}
         name={OFFER_CREATE_FORM_FIELDS.advertiser_id}
         error={getFieldErrorMessage(OFFER_CREATE_FORM_FIELDS.advertiser_id)}
         form={form}
         placeholder={OFFER_CREATE_FORM_FIELDS_PLACEHOLDER.advertiser_id}
       />

       {/* Offer model */}
       <ModelSelect
         label={OFFER_CREATE_FORM_FIELDS_LABEL.model}
         name={OFFER_CREATE_FORM_FIELDS.model}
         error={getFieldErrorMessage(OFFER_CREATE_FORM_FIELDS.model)}
         form={form}
         placeholder={OFFER_CREATE_FORM_FIELDS_PLACEHOLDER.model}
       />

       {/* Submit button with loading state */}
       <Button loading={isPending} type="submit">
         Submit
       </Button>
     </Stack>
   </form>
 )
}

Overall

Thus, thanks to the fact that the OFFER_CREATE_FORM_FIELDS field object and the OFFER_CREATE_FORM_VALIDATION_SCHEMA validation scheme are tied to the OfferPostBody type, we have a form that is quite easy to maintain, due to the fact that:

• uniform field naming is used. It is easy to refactor through IDE tools to access fields;
• a single binding to the OfferPostBody type is used. If this type is changed (scheme regeneration), we will get full illumination of places in the code that do not correspond to the new API scheme;
• strict typing of form field values and data sending function.

You can find the full code on GitHub here: fully-typed-form.

Fully typed forms based on API schema with react-hook-form, openapi-typescript and yup validation was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hello everyone! My name is Dmitry Pashkevich, and I’m a Frontend developer at Quadcode. Today I’ll share a method for passing environment variables to a statically built website using the Vite build tool in conjunction with the Nginx web server.

A common task in frontend development is passing environment variables to the application depending on the environment in which the application is running. It seems like a simple task, and everything is described in the documentation — just place a .env file next to it and run the build… on each environment.

It seems like the solution has been found. But this leads to a situation where each environment has a different build process and a different result of this build.

Practice shows that problems arise with the functionality of the build steps. For example, when making changes, settings, scripts, etc. are forgotten to be updated for one of the environments. As a result, we encounter issues with the application itself, as the artifacts also differ.

Thus, it seems logical to obtain a single build artifact for all available environments and be able to pass environment variable values. Therefore, it is easier to troubleshoot one issue with variable values than to investigate build steps as well.

Now, let’s see how to do this using the Vite and Nginx tools as an example.

Repository Preparation

First, let’s create a project from the template provided by the Vite builder for React + Typescript.

npm create vite@latest vite-nginx-dynamic-env-variables-example -- 
--template react-ts && cd vite-nginx-dynamic-env-variables-example && npm 
instal

Project Configuration Preparation

After successfully executing the commands, let’s open the resulting project in our favorite IDE and start creating the target solution.

Let’s adjust the file src/vite-env.d.ts. We will add a description of the type of available environment variables to enable IDE hinting.

/// <reference types="vite/client" />

interface ImportMetaEnv {
    readonly VITE_VERSION: string
}

interface ImportMeta {
    readonly env: ImportMetaEnv
}

Now the IDE will provide hints about the available environment variables.

Next, let’s create a file with environment variable templates: src/shared/projectEnvVariables.ts and add the following content to it.

type ProjectEnvVariablesType = Pick<ImportMetaEnv, 'VITE_VERSION'>


// Environment Variable Template to Be Replaced at Runtime
const projectEnvVariables: ProjectEnvVariablesType = {
   VITE_VERSION: '${VITE_VERSION}',
}


// Returning the variable value from runtime or obtained as a result of the build 
export const getProjectEnvVariables = (): {
   envVariables: ProjectEnvVariablesType
} => {
   return {
       envVariables: {
           VITE_VERSION: !projectEnvVariables.VITE_VERSION.includes('VITE_') ? projectEnvVariables.VITE_VERSION : import.meta.env.VITE_VERSION,
       }
   }
}

Next, it is necessary to make a change to the build configuration in vite.config.ts so that the file created above has a predictable name after the build stage. To do this, add a section with the configuration for rollup to the config.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
   plugins: [react()],
   build: {
       rollupOptions: {
           output: {
               format: 'es',
               globals: {
                   react: 'React',
                   'react-dom': 'ReactDOM',
               },
               manualChunks(id) {
                   if (/projectEnvVariables.ts/.test(id)) {
                       return 'projectEnvVariables'
                   }
               },
           },
       }
   }
}

In the manualChunks section, we create a custom chunk and save part of its name so that after the build, we can find this file for substituting environment variables.

Let’s make changes to the src/App.tsx file to see the values of environment variables.

import { getProjectEnvVariables } from "./shared/projectEnvVariables.ts";

const { envVariables } = getProjectEnvVariables()

function App() {
 return (
     <>
         <h1>VITE_VERSION</h1>
         <div>{envVariables.VITE_VERSION}</div>

         <hr />

         <h2>import.meta.env.VITE_VERSION</h2>
         <div>{import.meta.env.VITE_VERSION}</div>
     </>
 )
}

export default App

Next, let’s run the build to make sure that we obtain the necessary chunk for substituting variables after the build stage.

npm run build

After the build is complete, navigate to the dist/assets directory. You will see that a chunk named projectEnvVariables*, which we specified in the configuration above, exists.

Next, let’s conduct a series of experiments.

For ease of understanding that the desired build result is obtained, each build will be performed with a specified environment variable. This will visually verify the condition for returning the value of the environment variable in the getProjectEnvVariables function.

For the first experiment, create a .env file in the project root with the following contents.

VITE_VERSION=dev

Let’s start the project build and the mode to view the build results.

npm run build && npm run preview

Upon navigating to http://localhost:4173/, you will see two identical values of the variable read from the config and directly from the environment variable.

For the second experiment, let’s replace the variable in the dist/assets/projectEnvVariables-wa84hTgi.js file, which was generated after building the application. Replace the line with the value ${VITE_VERSION} with dev_from_env in this file. After refreshing the page in the browser, you will get the updated version of the variable on the screen, read from the config getProjectEnvVariables.

Everything works as expected! It’s time to automate variable substitution.

Preparing Docker + Nginx Configuration

We’ll demonstrate the automation of variable substitution using a Docker container containing the Nginx web server, which executes initialization scripts before startup, and substitutes environment variables using envsubst.

Let’s create a .docker directory in the project root with the configuration contents for the Nginx web server that will serve the application. A complete example of the Nginx configuration can be found in the repository, and below is the bash code of the .docker/app/nginx/init-scripts/100-init-project-env-variables.sh file, which replaces the environment variables.

#!/usr/bin/env sh

set -ex


# Find the file where environment variables need to be replaced.
projectEnvVariables=$(ls -t /usr/share/nginx/html/assets/projectEnvVariables*.js | head -n1)

# Replace environment variables
envsubst < "$projectEnvVariables" > ./projectEnvVariables_temp
cp ./projectEnvVariables_temp "$projectEnvVariables"
rm ./projectEnvVariables_temp

Next, in the project root, create a Dockerfile with the following content, which describes the application build and runs the Nginx web server to serve the static files.

FROM node:20-alpine as builder

WORKDIR /app

COPY package.json package-lock.json ./

RUN npm ci

COPY . .

ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}

RUN npm run build

FROM nginx:alpine

ARG VITE_VERSION=dev
ENV VITE_VERSION=${VITE_VERSION}

ARG PORT=80
ENV NGINX_PORT=${PORT}
ENV NGINX_HOST=localhost

EXPOSE ${PORT}

COPY .docker/app/nginx/nginx.conf /etc/nginx/nginx.conf
COPY .docker/app/nginx/conf.d/ /etc/nginx/conf.d/
COPY .docker/app/entrypoint.sh /entrypoint.sh
COPY .docker/app/nginx/init-scripts/ /docker-entrypoint.d/

WORKDIR /usr/share/nginx/html

COPY --from=builder /app/dist ./

Next, let’s build the container.

docker build -t 
vite-nginx-dynamic-env-variables-example .

Next, let’s run the created container with a new value for the environment variable available in the application.

docker run -p 81:80 -e VITE_VERSION=FROM_NGINX 
vite-nginx-dynamic-env-variables-example

Upon navigating to http://127.0.0.1:81 , we see that the environment variable is initialized with the current value, while the directly read environment variable remains with the old value.

Conclusion

This way, environment variables can be substituted into a statically built application at runtime, allowing for a unified build across all environments.

The code can be found in the repository.

Vite, Nginx and environment variables for a static website at runtime was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

You probably know about one of the unpleasant effects that arise during the operation of PostgreSQL — the table bloat effect. I want to tell you about how to prevent bloat and what to do if it has already appeared in your system.

Firstly, let’s briefly discuss the mechanism of its occurrence. To maintain data consistency, PostgreSQL uses the MVCC (Multiversion Concurrency Control) model. This means that each transaction sees a specific snapshot of the database at the moment the transaction begins. To make this possible, each row stores all its states because they might be needed by someone. And if you delete or update a row, in fact, the row remains in an unchanged state, but becomes invisible to new transactions. PostgreSQL has a VACUUM mechanism to clear the database, which marks the rows that are definitely no longer needed as free for use. However, “holes” remain inside the table, leading to bloat. Bloat in indexes occurs in a similar way.

How to understand if your tables have bloat?

Firstly, there are a large number of queries based on PostgreSQL statistics that provide estimated information about tables or indexes. You can choose the one you like; in general, they use the same data and should not differ significantly. I use queries from this repository. These queries work quite quickly since they do not fully scan the tables, but they can give some inaccuracies. To assess whether there are problems with your tables, this inaccuracy can be ignored.

However, if you need accurate information, you can use the pgstattuple extension. It provides information on the size of the table itself and how much space is occupied by “live” rows. The downside of this extension is that it fully scans the entire table, which can load your DB and take a considerable amount of time.

Is Bloat in Tables a Problem?

There is a clear problem associated with bloat: the table and its indexes take up a lot of disk space, which is never free. Sometimes bloat can account for up to 99% of the size of the table itself. This also relates to the second problem: when a table becomes bloated, the database needs to scan much more data for queries, which affects the performance of the database, sometimes quite significantly.

How to Prevent Bloat

• Avoid long transactions. Long transactions interfere with the vacuum’s work, or rather, they postpone the deletion of dead rows (because they are still visible to your long transaction). As a result, holes turn out to be bigger and take longer to clear. I recommend enabling logging for long transactions, so you can later understand from the logs what is causing the slowdown. This is controlled by the log_min_duration_statement parameter. For example, if you add to postgresql.conf:

log_min_duration_statement=1000

any queries that take longer than one second to execute will be logged.
To limit long queries, add a cron job that will prevent very long operations from executing, like this:

/usr/bin/psql -xt -c “SELECT PG_TERMINATE_BACKEND(pid)FROM 
pg_stat_activity WHERE xact_start < NOW() — ’10 min’::INTERVAL 
AND state != ‘idle’ AND usename != ‘postgres’”

Also, PostgreSQL has a parameter statement_timeout, but the documentation explicitly advises against setting it globally. Use it when you execute a query (perhaps manually, perhaps from an application) and want to control its execution time:

BEGIN;
SET LOCAL statement_timeout = 1000;
SELECT …;
COMMIT;

• Configure autovacuum. There are quite a few settings here, let’s consider some of them. By default, autovacuum triggers when more than 20% of the rows in a table have changed, but the larger the table, the longer these changes will accumulate. This is controlled by the autovacuum_vacuum_scale_factor setting, and you can decrease it globally or for a specific table. Moreover, if you are configuring autovacuum for a specific table, in some cases you can even set autovacuum_vacuum_scale_factor to 0, while increasing autovacuum_vacuum_threshold:

alter table tablename set (autovacuum_vacuum_scale_factor = 0,
autovacuum_vacuum_threshold = 1000000); 

As a result of executing the command, autovacuum for this table will trigger after every million modified rows, regardless of the table size.
Ensure you have enough autovacuum workers. The autovacuum_max_workers setting determines the maximum number of workers, and if all of them are busy (by default, there are only 3), this can mean that some table already requires maintenance but isn’t getting it. The easiest way to check the number of active workers is with the following query:

select COUNT(*) from pg_stat_activity where query like ‘autovacuum:%’

If the autovacuum can’t keep up, that’s a significant problem. You need to increase the aforementioned autovacuum_max_workers, and there are also a number of steps you can take to speed up autovacuum’s work. I won’t go into all the settings in detail, but I will list the ones to pay attention to:

1. maintenance_work_mem — increase if the server’s memory allows.
2. autovacuum_vacuum_cost_delay — decrease if disk performance allows.
3. vacuum_cost_limit — increase if disk performance allows.
4. autovacuum_naptime — decrease if disk performance allows.

• PostgreSQL has a built-in mechanism that helps prevent bloat — HOT (Heap Only Tuples). Thanks to this mechanism, first, new entries do not appear in indexes for updated rows, and for tables, rows can be marked as free even without performing a vacuum on the table, which indirectly also reduces bloat. But there are two important limitations. First, the updated columns must not be part of any index on the table. Second, the new (updated) row must be on the same page as the old one, meaning there must be enough space. This can be controlled by setting the fillfactor parameter for the required tables:

ALTER TABLE tablename SET (fillfactor = 70);

I recommend that you explore this feature for tables that are frequently updated, but I must note that the benefits of using this mechanism will depend on the specific conditions. For example, I personally couldn’t achieve significant improvements for tables where I tried to play with settings for HOT.

• In another article about working with PostgreSQL for developers, I discussed several nuances that also lead to an increase in bloat, which you can’t influence from the PostgreSQL side, but you can influence from the application side. I provided recommendations for effective work there, and I recommend checking it out as well.

How to deal with Bloat

When bloat has already occurred for your tables, you obviously want to get rid of it. Here are several methods we use:

VACUUM

The obvious method provided by the database itself is to manually execute the VACUUM FULL command. Unlike a regular VACUUM, this operation completely rewrites the table and indexes, and the holes are closed. However, this operation requires a lock on the table, so its use is usually not recommended. But it is not prohibited, and in some cases, you can do it quite safely. First, you might have maintenance windows during which you can maintain the database without affecting the application, then you just need to make sure that you fit into this window. Second, if you have a small table, perhaps its maintenance will take seconds, and you can afford to run VACUUM FULL (I recommend running it with a specified statement_timeout, as I showed above).

REINDEX CONCURRENTLY

This won’t help you get rid of bloat in tables, but it will help get rid of bloat in indexes, and in some cases, that’s enough. Given that this functionality is built-in and safe to apply, it’s worth keeping in mind. Be sure to call the command with the CONCURRENTLY option. Otherwise, the database will take a lock on the table:

REINDEX TABLE CONCURRENTLY my_table

pg_repack

This is a quite popular utility that also completely recreates the table, but unlike VACUUM FULL, it does so without long locks on the table. At the start, a table with a log of changes in the table is created, and the table where the data will be copied is also created. After copying is complete, all changes from the log are applied, and the new table replaces the original. Installation and usage example:

sudo apt-get install postgresql-15-repack
sudo -u postgres psql -c “CREATE EXTENSION pg_repack” -d my_db
sudo -u postgres pg_repack -d my_db -t my_table1 -t my_table2

You can run pg_repack without specifying tables, but in this case, all tables in the database will be processed, and it’s unlikely that all your tables need to be recreated. Especially since pg_repack has nuances in its operation that you should be aware of:

• pg_repack creates a copy of the table with its indexes, so you need to have at least enough space on your DB server for another table. Since fighting bloat often starts when disk space is already running out, this can be a problem. I advise first finding small tables that can be compressed and processing them, and then moving on to larger tables.
• pg_repack cannot process any table. It requires that a table has a Primary Key or unique indexes. An index always creates an additional load on the database, so I cannot recommend creating an index just for pg_repack’s operation. Of course, you can create it and delete it after maintenance, or you can use other methods.
• pg_repack creates a significant load on the disk. Since its main advantage is that it does not require prolonged locks, it is used when the database is under production load, and the additional disk load will lead to the degradation of database and application performance. In theory, you can try to reduce the I/O priority of the process copying the table using the `ionice` utility. But, for example, in modern Ubuntu, the default I/O scheduler is mq-deadline, which does not allow you to change the priority. Or choose a time of the lowest load on the database.
• In addition to the disk load, network load will be created to copy the generated WAL files to your replicas. In our case, we easily hit two gigabits, after which interesting effects start to occur. Of course, the replica begins to lag. In itself, this is not a problem, but if your application also connects to the replica and expects up-to-date data there, it may start to work incorrectly. But in addition to this, at some point, the WALs on your master start to rotate, and it is quite possible that the replica has not yet managed to read them, and the master has already deleted them. As a simple solution, you can increase the wal_keep_size parameter on the master so that it stores enough data for the replica to keep up. As for the applications — we redirected all traffic to the master during maintenance. Later, we solved the problem more radically — we installed 10GB network cards on such servers, but this is usually not the fastest solution.
• The utility creates long transactions. I have already written above about why this can be bad. It is impossible to influence this, but it must be kept in mind.

pgcompacttable

This utility fights bloat using the same mechanisms that create it. If you update a row without changing the column value, the new version will be written to a free space in the database (of course, provided that the conditions for HOT are not met, as I wrote about earlier). So, if you update the rows page by page, the pages will be freed up. This is exactly what pgcompacttable does, leaving unoccupied pages at the end of the table. Under such conditions, vacuum can remove this end of the table and free up space. Example of use:

curl -s https://raw.githubusercontent.com/dataegret/pgcompacttable/master/bin/pgcompacttable -o pgcompacttable
chmod +x pgcompacttable
sudo apt-get install libdbi-perl libdbd-pg-perl
sudo -u postgres psql -c “create extension if not exists pgstattuple” -d mydb
sudo -u postgres pgcompacttable -h /var/run/postgresql -d my_db

Let me give you a more detailed comparison of the usage differences with pg_repack:

• The utility collects bloat statistics using the pgstattuple extension, so you can run it across the entire database, and it will decide for itself what needs to be “compacted” and what does not.
• pgcompacttable can limit its operational speed, meaning the impact on the disk can be regulated. However, I should note that this applies only directly to the process of updating rows; the vacuum, reindex procedures, and statistics collection using pgstattuple cannot be limited by the utility.
• You won’t need a lot of additional disk space. All manipulations are performed in the same table, so the table will not grow. However, indexes are recreated using built-in Postgres tools, and additional space will be required for them.

Yet, there are also special considerations that you need to be aware of.

• I mentioned that the utility can only regulate the load it directly generates. At the same time, a bloat assessment using pgstattuple is called for each table, and for large tables, this process is lengthy and disk-intensive as the extension scans every page in the table. In such cases, I replaced the use of the pgstattuple function with pgstattuple_approx. The utility is written in Perl, and it is quite simple to modify. You can use my fork, which already supports this. As for the load from vacuum, the easiest way is to adjust the vacuum_cost_delay parameter — by default, it is 0, which means the vacuum is not limited in any way.
• Just like with pg_repack, the issue of generating a large number of WAL files and potential replication lag is relevant — you need to monitor this.
• You also need to watch out for long-running transactions.
• The vacuum has an unpleasant feature where it “trims” the end of the table (which is the expected behavior when working with pgcompacttable). When applying these changes to a replica, the table on which this occurs is locked for reading (on the replica, of course). This effect can be minimized if vacuum is called during operation, not just at the end of row transfer (controlled by the — routine-vacuum), but, unfortunately, this does not always help. The vacuum for trimming the table takes short-term locks, and if there is intensive writing to the table, it may not complete this process. And this means that the table may later be trimmed by autovacuum, and this can happen at any moment.

Of course, these utilities have a large number of settings that I am not covering here, because they are not directly related to the features I have described. I strongly recommend that you approach their launch very carefully, monitor the metrics of the database and application, because even considering that you now know about their features, they can still impact the performance of your applications.

I hope that this article will help you combat bloat in your databases, or even better, prevent its occurrence in the first place. Feel free to ask your questions in the comments, I will be happy to answer them.

Bloat in Postgresql. How to live with it? was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hello everyone! My name is Dmitry Pashkevich, and I’m a Frontend developer at Quadcode. This article isn’t just a tutorial on creating a unified ESLint configuration that can be reused between projects. It’s a story about solving the pain of discussions about code formatting from project to project during reviews.

The article will be useful for developers who want to standardize their approach to code formatting across different projects; looking for a proven solution for codebase standardization.

[SPOILER ALERT] You can review the code in our repository on GitHub repository as well as find the package in NPM.

Why do we need a unified ESLint plugin/configuration?

Uniform code formatting in a team reduces the mental load during code reviews, reading/writing code, or starting a new project. It allows one to focus on how the code works rather than being distracted by how semicolons are placed.

Imagine you have 5 projects, and each has its own formatting rules. You start the 6th and copy configs from previous projects, adding new rules. And so on in a loop. We end up with inconsistent ESLint configs in all projects and, as follows, inconsistently formatted code between projects. As a result, simple things are discussed over and over during code reviews.

In this article, I will explain how to write a plugin/configuration for ESLint and publish it as a package. This will allow you to correct, add, and change the necessary rules in one place and connect them as a single module in other projects.

In our Quadcode team, we use publication to a private registry, but in this article, you’ll see publication to NPM (in the source code).

Repository Preparation

So, the first thing we’ll start with is creating a template for the ESLint plugin project.

To do this, go to the ESLint documentation, the “Create Plugin” section, and follow the recommendation for creating a new project. Navigate to the installation section and perform the required actions.

Open the command line.

Installing Node.js

If you haven’t installed the Node.js platform yet, you need to do so.

Installing Yeoman

Next, install Yeoman — a tool for generating template projects, if you haven’t installed it yet.

npm i -g yo

Installing the ESLint Plugin Generator

Next, we’ll install a utility to generate an ESLint plugin.

npm i -g generator-eslint

Great! All preliminary work is done, now it’s time to create the base project for our plugin.

Creating the Project Directory

Let’s create a directory for our project.

mkdir eslint-plugin-nimbus-clean

And navigate into it.

cd ./eslint-plugin-nimbus-clean

Next, we’ll set up the project structure.

yo eslint:plugin

This command will start the wizard for creating an ESLint plugin project.

Answering the Setup Wizard’s Questions

Let’s go through a short survey.

? What is your name? dipiash
? What is the plugin ID? nimbus-clean
? Type a short description of this plugin: A comprehensive linting solution that sweeps your code clean
? Does this plugin contain custom ESLint rules? No
? Does this plugin contain one or more processors? No

The last two questions were answered with “No” because at this stage, we won’t be using any custom rules or custom processors. Instead, we will use a certain combination of other plugins.

Wait for the generator to create the starting project and open the resulting project in your IDE.

Setting Up .gitignore File

Next, we will create a “.gitignore” file to exclude unnecessary files from being committed to the repository.

touch .gitignore

To avoid drafting this file’s content from scratch, I always use the service: https://www.toptal.com/developers/gitignore. You can also find plugins for your IDE that allow you to generate this file directly there.

We’re interested in “.gitignore” for Node.js — take the content from the link and add it to the “.gitignore” file we created earlier.

Initializing git

Initialize the git repository.

git init

Project Preparation

Let’s make changes to the created project.

In the future, we might need to write custom rules. Let’s immediately add a plugin for linting ESLint rules and connect it as indicated in the documentation.

npm install eslint-plugin-eslint-plugin - save-dev

In the package.json file, in the “scripts” section, add two commands: “build” and “pack”.

The “build” command will compile our project.

rm -rf ./dist && mkdir ./dist && cp -r ./lib/* ./dist

The “pack” command will be needed to locally check the plugin’s operation.

npm pack - pack-destination=./dist

We should also adjust the sections: “main”, “exports”, and “files”, as the content for npm publication will be located in the “dist” directory.

"main": "./dist/index.js",
"exports": "./dist/index.js",
"files": [
  "/dist",
  "README.md",
  "package.json"
]

Additionally, let’s edit the “lib/index.js” file. We won’t need the require index package, so remove that part of the code.

ESLint Plugin vs. ESLint Config

When setting up ESLint, one can often encounter packages with names starting with: “eslint-plugin-*” and “eslint-config-*”. So, what’s the difference?

Plugins must be named as “eslint-plugin-*”. When adding a plugin to your project, the rules won’t be enabled automatically, and therefore you will need to enable each rule individually.

Configs must be named as “eslint-config-*”. When adding a config to your project, all rules will be enabled automatically, and you won’t need to enable each rule individually.

In practice, plugins are needed if you are creating your own code linting rules and want the plugin users to be able to turn them on or off by themselves. In all other cases, you can use a config since it will most likely simply reuse a set of configurations from other plugins.

However, a plugin can also be used as a config with general rules enabled by default. In this article, we will consider such a plugin version that includes a default configuration (recommended). Often in the documentation for plugins, one can see that such plugins are connected to the “extends” section as “plugin:your-plugin-name/recommended” — more details can be found in the ESLint documentation.

Set of Configs / Plugins

Next, let’s determine the main plugins that we will use in our projects.

ESLint

This is directly the eslint itself, from which we will take the recommended config.

Prettier

So as not to use a separate configuration for Prettier, we’ll add to our ESLint plugin/config the rules from the packages:

• eslint-config-prettier — disables all rules that are unnecessary or might conflict with Prettier.
• eslint-plugin-prettier — allows us to set up Prettier as ESLint rules and will display information about problems as ESLint issues.

Imports

Let’s set up rules for working with import/export in our code.

• eslint-plugin-import — will allow us to avoid various issues when importing/exporting modules in the code.
• eslint-import-resolver-typescript — will add TypeScript support for the previous plugin.
• eslint-plugin-simple-import-sort — will allow us to configure module sorting in the desired order according to certain rules.

React

Since all our projects are written using React, we will naturally add linting support for code written with React.

• eslint-plugin-react — rules for linting React code.
• eslint-plugin-react-hooks — will help us adhere to the rules for writing React Hooks.
• eslint-plugin-testing-library — will check the code of our tests for the Testing Library.
• eslint-plugin-jsx-a11y — will check if we have added accessibility rules to our JSX elements or not.

Typescript

Since the entire codebase is written in TypeScript, we will add rules for linting TypeScript code — @typescript-eslint/eslint-plugin.

Promises

We will add a plugin for linting code that works with Promises — eslint-plugin-promise.

Code quality

And we will add two final plugins for linting code quality.

• eslint-plugin-sonarjs — will help identify potential bugs and the use of suspicious patterns in the code.
• eslint-plugin-unicorn — more than 100 useful rules for ESLint.

We will install all the packages listed above and add them as peerDependencies in package.json.

npm i -D eslint-import-resolver-typescript @typescript-eslint/eslint-plugin 
eslint-config-prettier eslint-plugin-import eslint-plugin-jsx-a11y eslint-
plugin-prettier eslint-plugin-promise eslint-plugin-react eslint-plugin-react-
hooks eslint-plugin-simple-import-sort eslint-plugin-sonarjs eslint-
plugin-testing-library eslint-plugin-unicorn

Also, to ensure the user sees the entire list of missing projects when installing our package, we will use the directive in package.json peerDependenciesMeta and mark each dependency as `optional: false`.

Rules for ESLint

In this section, I will describe the inclusion of rules for each section from the previous one — I will describe in the same order.

Let’s create a `rules` directory in `lib` — where files for each part of the config will be located.

mkdir ./rules/lib

ESLint

Let’s create a file to describe the ESLint configuration.

touch lib/rules/common.js

And add the rules there.

/** eslint */
module.exports = {
    // https://eslint.org/docs/latest/rules/curly
    "curly": ["error", "all"],
    // https://eslint.org/docs/latest/rules/padding-line-between-statements
    "padding-line-between-statements": [
        "error",
        { "blankLine": "always", "prev": ["const", "let", "var"], "next": "*" },
        { "blankLine": "any", "prev": ["const", "let", "var"], "next": ["const", "let", "var"] },
        { "blankLine": "always", "prev": "*", "next": "return" }
    ],
    // https://eslint.org/docs/latest/rules/no-multiple-empty-lines
    "no-multiple-empty-lines": ["error"],
    // https://eslint.org/docs/latest/rules/arrow-body-style
    "arrow-body-style": ["error", "as-needed"],
    // https://eslint.org/docs/latest/rules/prefer-arrow-callback
    "prefer-arrow-callback": "off",
    // https://eslint.org/docs/latest/rules/no-console
    "no-console": ["error", { "allow": ["warn", "info", "error"] }],
    // https://eslint.org/docs/latest/rules/no-underscore-dangle
    "no-underscore-dangle": [
        "error",
        {
            "allow": ["_id", "__typename", "__schema", "__dirname", "_global"],
            "allowAfterThis": true
        }
    ],
}

Prettier

Let’s create a file to describe the Prettier configuration.

touch lib/rules/prettier.js

Add the rules.

/** eslint-plugin-prettier */
module.exports = {
    "prettier/prettier": "error",
}

Imports

Let’s create a file to describe the configuration for “eslint-plugin-import” and “eslint-plugin-simple-import-sort”.

touch lib/rules/import.js

touch lib/rules/simple-import-sort.js

Add the rules.

/** eslint-plugin-import */
module.exports = {
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/first.md
    "import/first": "error",
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/newline-after-import.md
    "import/newline-after-import": "error",
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-duplicates.md
    "import/no-duplicates": "error",
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/prefer-default-export.md
    "import/prefer-default-export": "off",
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-anonymous-default-export.md
    "import/no-anonymous-default-export": [
        "error",
        {
            "allowArray": false,
            "allowArrowFunction": false,
            "allowAnonymousClass": false,
            "allowAnonymousFunction": false,
            "allowCallExpression": true,
            "allowLiteral": false,
            "allowObject": true
        }
    ],
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-unassigned-import.md
    "import/no-unassigned-import": "off",
    // https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-unused-modules.md
    "import/no-unused-modules": "error"
}

React

Let’s create a configuration file for React.

touch lib/rules/react.js

Add the rules.

/** eslint-plugin-react-* */
module.exports = {
    // https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/prop-types.md
    "react/prop-types": "off",
    // https://github.com/facebook/react/blob/main/packages/eslint-plugin-react-hooks/README.md
    "react-hooks/exhaustive-deps": [2],
}

TypeScript

Let’s create a configuration file for TypeScript.

touch lib/rules/typescript.js

Add the rules.

/** @typescript-eslint-* */
module.exports = {
    // https://typescript-eslint.io/rules/no-use-before-define/
    "@typescript-eslint/no-use-before-define": ["error"],
    // https://typescript-eslint.io/rules/no-unused-vars/
    "@typescript-eslint/no-unused-vars": [
        "error"
    ],
    // https://typescript-eslint.io/rules/no-explicit-any/
    "@typescript-eslint/no-explicit-any": "error",
    // https://typescript-eslint.io/rules/naming-convention/
    "@typescript-eslint/naming-convention": [
        "error",
        {
            "selector": "interface",
            "format": ["PascalCase"],
            "custom": {
                "regex": "[A-Za-z]Interface$",
                "match": true
            }
        },
        {
            "selector": "typeAlias",
            "format": ["PascalCase"],
            "custom": {
                "regex": "[A-Za-z]Type$",
                "match": true
            }
        }
    ],
    // https://typescript-eslint.io/rules/ban-types/
    "@typescript-eslint/ban-types": [
        "error",
        {
            "types": {
                // un-ban a type that's banned by default
                "{}": false
            },
            "extendDefaults": true
        }
    ]
}

Promises

Let’s create a configuration file for Promises.

touch lib/rules/promise.js

Add the rules.

/** eslint-plugin-promise */
module.exports = {
    // https://github.com/eslint-community/eslint-plugin-promise/blob/main/docs/rules/prefer-await-to-then.md
    "promise/prefer-await-to-then": "off",
    // https://github.com/eslint-community/eslint-plugin-promise/blob/main/docs/rules/always-return.md
    "promise/always-return": "off",
    // https://github.com/eslint-community/eslint-plugin-promise/blob/main/docs/rules/catch-or-return.md
    "promise/catch-or-return": [2, { "allowThen": true, "allowFinally": true }],
}

Code Quality

Let’s create a configuration file for ESLint.

touch lib/rules/sonarjs.js

touch lib/rules/unicorn.js

Add the rules.

/** eslint-plugin-sonarjs */
module.exports = {
    // https://github.com/SonarSource/eslint-plugin-sonarjs/blob/master/docs/rules/no-identical-functions.md
    "sonarjs/no-identical-functions": ["error", 5],
}

/** eslint-plugin-unicorn */
module.exports = {
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-array-reduce.md
    "unicorn/no-array-reduce": "off",
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prefer-module.md
    "unicorn/prefer-module": "off",
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-null.md
    "unicorn/no-null": "off",
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-useless-undefined.md
    "unicorn/no-useless-undefined": "off",
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/filename-case.md
    "unicorn/filename-case": [
        "error",
        {
            "cases": {
                "pascalCase": true,
                "camelCase": true
            },
            "ignore": [
                "next-env.d.ts",
                "vite(st)?.config.ts",
                "vite-environment.d.ts",
                "\\.spec.ts(x)?",
                "\\.types.ts(x)?",
                "\\.stories.ts(x)?",
                "\\.styled.ts(x)?",
                "\\.styles.ts(x)?",
            ]
        }
    ],
    // https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prevent-abbreviations.md
    "unicorn/prevent-abbreviations": [
        "error",
        {
            "checkFilenames": false
        }
    ],
}

Publishing an NPM package

To publish the package, we will use the following utilities:

• release-it + @release-it/bumper + @release-it/conventional-changelog
• @commitlint/cli + @commitlint/config-conventional
• commitizen + cz-git + cz-conventional-changelog

These utilities will allow us to version our ESLint plugin according to SemVer and describe commits in such a way that it occurs automatically and a CHANGELOG is generated. You can see the entire setup in the repository.

Integration into a Project

After publishing to NPM, you can install and integrate the package into any of your projects.

npm i eslint-plugin-nimbus-clean

Setting up the ESLint configuration.

{
    "extends": [
      "plugin:nimbus-clean/recommended"
    ]
}

Detailed instructions are described in the project’s README.

Conclusion

This is my experience in creating custom configurations and plugins for ESLint and publishing them to NPM.

Using this approach, you can create the desired configuration for your projects once and then reuse it. If you need to make some changes to the ESLint config, it only needs to be done in one place, and in the projects, you just need to update the version if necessary.

What else would you recommend adding to this plugin?

You can see all the code in the Github repository, and the package can be found on NPM. I will be glad if you can star the repository:) Feel free to ask me any questions in the comments below.

Improving development productivity: the magic of a unified ESLint configuration was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

We love postgres very much! We love it and know how to manage it. At the moment, the number of postgres clusters in our production environment is approaching 200, and we have accumulated some experience in working with it that I would like to share.

I will talk about the problems our developers encountered while working with postgresql, which were related to the specificities of this database (including the specifics of our installations). I must clarify that just because something may lead to problems does not mean it should not be done, but it is important to understand how the database works, how it can behave, and how to prevent issues that may occur with it.

Since the target audience of this article is developers, I assume that you will not need to set up the database yourself, so I do not provide specific instructions on the parameters discussed.

I’ll say a few words about our installations — there is no unique configuration here, but it is also necessary to consider.

We use a connection pooler — pgbouncer, which is installed on each host with the DB, and applications can only work through it. This pooler has an important setting that determines when a connection to the server can be reused. The default setting — session, means that the connection will be kept by the client until it disconnects, but we set it to transaction, which means that after the client completes the transaction, the connection to the server will be returned to the pool and can be reused. This greatly increases the benefit of using pgbouncer because we can: 1) limit the number of connections to postgresql (each connection is relatively expensive for the database); 2) we have greater flexibility in database maintenance (through pgbouncer we can pause queries to the DB or transparently redirect queries to another DB).

Developers can create dev environments on their own, so sometimes an application during development might connect directly to the database, and the specifics of working with pgbouncer might not be considered. Let’s discuss some of these challenges.

Prepared Statements

Even if a developer does not explicitly use prepared statements, their framework might do so. However, prepared statements cannot work with pgbouncer because the query itself is sent first, and the data for it arrives as a separate transaction that can end up in a different session — in this case the database will show an error. There are workarounds for almost any library. For example, for the popular golang library lib/pq, you need to add the parameter “binary_parameters=yes” to the database connection string.

Session Parameter Changes

Other problems with pgbouncer are also related to the reuse of connections. For example, if you have an application component that changes the search_path for its operation, it will affect its neighbors who were expecting the default search_path. When they call functions or tables without specifying a schema, they will get an error. A more trivial case is when someone connects to the database using the application’s credentials through a bouncer, and the client sets the session parameter to “read-only”. As a result, all queries going through such a connection will not have write permission.

There are also some PostgreSQL features that simply cannot work through pgbouncer. For example, we encountered the impossibility of using advisory locks and listen/notify. In exceptional cases, we compromise — we set up two pgbouncers, one in session mode, the other in transaction mode. In this case, the application implements logic that selects the appropriate connection based on its needs.

Row Updates and Deletions

One of the things you need to know when working with PostgreSQL is how updates and deletions of rows work in this database. When an update occurs, a new row is created. In both cases (an update and a deletion), the old row technically remains in the database and is only marked as deleted until a vacuum comes and frees up space.

However, there is an important nuance — the vacuum will only deal with rows that no one will definitely access anymore, meaning: if there is a transaction in the database that started before the row was deleted, the space will not be reclaimed. Moreover, freeing up space in most cases means that the database will be able to use the freed space for new data in the same table, rather than returning it to the operating system.

From this description, a fairly obvious problem arises: tables that are frequently updated (as well as indexes in such tables) can “bloat” because holes form in them. This is generally not a developer’s problem, as an experienced DBA will fine-tune the vacuum settings on the database side, but this can only be mitigated to a certain extent.

Potential Problems and How to Fix Them

So, my favorite use case related to this feature is creating a queue based on PostgreSQL. In this instance, a table is created with the tentative name “event,” into which one daemon adds events, and another daemon retrieves and then deletes them. Some logic with stored procedures or some rationale for deferred task execution may be added here, but the essence remains the same — a queue is a queue, and on any heavily loaded database, it will inevitably cause issues. At one point, the table will grow larger than usual, start lagging on reads, and as a result, will continue to grow. Moreover, such tables do not tolerate long transactions in the database (as a reminder, long transactions interfere with the operation of the vacuum). How to deal with this?

1) Don’t use a table as a queue. If it is necessary, look into pgq — an extension that implements a queue based on PostgreSQL. We use it quite successfully in our company, and it causes us far fewer problems. However, I should note that very long transactions (in our experience, several hours) are also poorly tolerated.

2) Don’t allow long transactions on the master. If you have such transactions in your application, move them to a replica and optimize them. Ask your DB administrator to set up the termination of long transactions. This is a less painful situation that doesn’t lead to fatal degradation but still worsens the life of the database. Imagine that you need to update a large number of rows in the database once, for example, you added a new field and want to fill it for all rows. After the update, you may be surprised to find that your table now occupies twice as much space. Such migrations should be carried out in batches because: a) I have just warned you about long transactions; b) you need to take sufficient breaks between batches at a certain frequency to allow the vacuum to operate in the database (you can even start it yourself).

An even more common scenario — there is a table with historical data in the database, and developers sometimes delete old data from this table. But, as you’ve already guessed, the space is not freed. Such tables are best partitioned by date. Then you can simply delete old partitions when you realize that you no longer need them.

In reality, the vacuum is not only needed to free up space from deleted rows. To ensure data versioning in PostgreSQL, the row also stores the transaction ID that created it and the one that deleted it. Consequently, the row will be visible to transactions that fall between these values. This ID consists of 4 bytes, meaning its size is limited, so it’s cyclical. For proper functioning, rows that are currently visible to all transactions (i.e., unchanged) are frozen by the vacuum. However, if the row isn’t frozen and the difference between the creation ID and the current transaction is less than half of the cycle (which is 2 billion entries), the database stops writing. 2 billion isn’t a small number, but it’s attainable.

In our experience, this happened on a test database. One Friday, a new version of the application was deployed to the test environment, which generated a huge load on the databases — 30k transactions per second. The auto-vacuum, unfortunately, couldn’t cope because the load on the database had already increased, and the hardware was weaker than in production. So in less than 20 hours, the database switched to read-only mode. In our case, this load occurred due to an application error. The main advice here is — don’t deploy on Fridays. The wraparound counter can also be monitored for each table, but in regular situations, we haven’t encountered this issue again.

The Change of a Schema and Vacuum

Vacuum does not write lock the table, so it can work smoothly in the background. However, in some cases, the vacuum can block changes to the table schema. And if, at that moment, you want to, for example, add a new column to the table or even create a partition, the schema modification procedure will wait for the vacuum to finish. On the other hand, schema modification locks table writes, so your schema modification operation, which is waiting for the vacuum to finish, will not allow writing operations on that table. This can be easily prevented:

• You can create a stored procedure that kills vacuum processes, which you will call before starting migrations.
• Before making schema changes, you can set a timeout for query execution, after which it will be canceled. This is a generally good practice because migration procedures can take a long time due to various reasons, which can be a surprise for you.

Developers often use replicas for read operations to reduce the load on the master. There can be unexpected nuances here too.

If you use long queries on a replica, the database server will pause replication and not apply new changes during this time. To resolve this, there’s a setting in postgres that interrupts queries longer than a specified duration. By default, it’s set to 30 seconds, which sometimes becomes a problem for developers who plan to delegate heavy and lengthy queries to replicas. You can increase this delay, but it means your replica will fall behind more. You can also pass information about the currently executing queries to the master; this will prevent canceling replica queries, but it means that such queries will affect the master’s vacuum execution and may lead to database bloat, as we already mentioned. In any case, it’s a trade-off, and you need to be aware of this feature and choose the most appropriate solution in each case.

Once, we encountered an interesting problem — our monitoring started to fail on one of our databases. It turned out that the script collecting information from the DB began timing out, and the timeout happened when gathering data from pg_stat_statements. Pg_stat_statements is a useful extension that allows us to analyze database queries. Semantically identical queries in this table are aggregated, allowing us to obtain statistics on queries even if they were invoked with different parameters. In our case, the application had massive insert queries, inserting up to 50,000 rows, each with 10 values. The resulting query size was more than 12 megabytes. The situation was further complicated because there weren’t exactly 50,000 rows, but slightly fewer (some were filtered by the application), and each time the number varied. As a result, pg_stat_statements couldn’t recognize these queries as similar, and a separate record was created for each of these queries.

When querying for statistics, the intermediate query result started weighing over a gigabyte, no longer fit into memory, and was written to disk. Queries utilizing temporary files take significantly longer, so we couldn’t fit within the allotted time for statistics collection. Initially, we tried to reset the pg_stat_statements statistics once a day, but that no longer worked. So, we consulted with our team to reduce the size of such queries (unfortunately, it would require significant refactoring of the application logic to make the queries identical). On the database side, we reduced the number of records stored in the statistics.

Conclusions

If you work with databases, it is essential to understand what happens behind the SQL queries you execute for your work to be maximally efficient. I hope this article helped shed light on some peculiarities. Nevertheless, I advise you, when adopting new patterns in database work, to study the possible impact on the database. I will be glad to answer all your questions or just discuss the article in the comments. Thank you!

Features of Working with Postgresql was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

Defining Product Requirements and, as a result, Design System Requirements

The process of defining product requirements began with the frontend (FE) team choosing suitable tools to implement the entire project, not just the design system, based on minimal requirements:

• React:

a) Server-Side Rendering (SSR) for the main page,

b) Client-Side Rendering (CSR) for the user dashboard.

• TypeScript.
• Work with REST/GraphQL/WebSockets.
• SSR support.
• React components should be covered by tests.
• Usage of modern transpilation tooling — Babel/Esbuild, etc.
• Enforced linting and code style (code analyzer).
• Defined project folder structure and agreement on code organization.
• Optional: use a UI kit and reuse it for components.
• Optional: ability to view the project’s UI kit and provide it to designers.

As a result of this selection, the following technologies and tools were chosen:

1. React + TypeScript
2. Eslint with a set of preferred rules
3. GraphQL — Apollo
4. TanStack Query
5. Schema-first approach for API development, generating TypeScript types from Swagger schemas
6. Styled-components
7. Vite as the project bundler
8. Storybook for component display
9. npm as the package manager (Yarn/pnpm/npm were considered)
10. Monorepo using NX
11. Feature-Sliced Design for code architecture and structure
12. Testing: unit tests, Jest (later transitioned to Vitest), RTL/snapshot testing
13. Monitoring with Sentry

At this stage, we also considered the UI kit and how we would build it:

• Possible use of react-hook-form for working with forms
• Using styled-system.com for building the UI, building from scratch, or exploring alternative options

The question of building the UI kit sparked heated discussions and extensive research. I had no desire to start from scratch and go through the process of creating a new set of components again (which I had already experienced and took a long time), while also encountering the same pitfalls. Additionally, it was clear at that time that building the UI kit would not take up much time.

After some more time spent on research and intense discussions, a solution emerged. We chose Mantine, although we considered other options such as Ant Design, Chakra UI, and Semantic UI. Mantine won our hearts with its project documentation and more. In the next section, I will provide more details on why we were so impressed with this tool. This choice became the starting point for working on the design system, and we already had a sense that it would be an entirely new experience.

Results of Working with Requirements or Why Mantine?

The result of the research was a rough draft of the application skeleton. You can check out an example on Github. The final solution differs from what is presented in the repository, but the concept is reflected. After creating the skeleton, we started working on the design system.

The development of the design system began by identifying the following basic elements:

- Color palettes

- Typography

- Margins/Padding

- Icons/Images

- Borders

- Radii (rounded corners)

- Patterns/UX/UI flows

- Animations

Based on this, we initially set up a configuration for theming (and now we are gradually building the design tokens system). As mentioned earlier, our design system is built using Mantine. So, what made it so useful? On the one hand, it might seem limiting because we are relying on a specific tool. But on the other hand:

Mantine is a clear and flexible tool

It provides:

• Documentation;
• Theming capabilities;
• Typing;
• Source code that can be used as supplementary/training/inspirational material;
• A broad set of basic, easily customizable components, most of which have been tested in projects and are supported by the community, indicating that they cover many typical use cases and have resolved enough bugs to be used in production;
• Components are broken down into layers, with almost every layer being customizable and stylizable. Again, if you need to do something specific, you can always take the source code of the basic elements and customize it or create a pull request;

In essence, for us, Mantine serves as the foundation for building our “home” = the design system.

Speed of development

Comparing the efforts required to create components from scratch versus using Mantine, it looks like this:

From scratch (under limited time constraints):

1. You come up with the logic of how the component will work in different states (default/active/focus/disabled, etc.) and then you program the logic/styles.

2. You think about how it can be styled externally (usually, people don’t think/suspect this at the start), and then there are slight differences here and there — no one breaks down the component into layers (each layer/element of the layer should be stylized).

3. There are also different variations of the component, and you have to implement logic and styles for them too.

a) Due to time constraints, it might end up being not very convenient to use and modify the API.

If we use Mantine:

You have a ready-made basic component, organized into layers with predefined states (default/active/focus/disabled, etc.) and behavior logic. Essentially, this is your limitation and safety in component creation.

You simply style the component according to your theme. Styling variations involve describing different styles for display based on the known classes for the layers.

If there is a need for some custom logic, it can be easily implemented through the standard component API or by modifying the source code, but within your own project.

I believe it is essential to note that at the product launch, sometimes it is necessary to simplify the interface and make reasonable assumptions because it is not always possible to achieve everything we want right away. Striking a balance is crucial.

According to some estimates, creating the final component based on Mantine is approximately 5–10 times faster than building it from scratch.

This is achieved because:

- The component’s parameters and layers are immediately clear.

- You can interactively view the component in the documentation, which gives you an understanding of its capabilities and limitations, along with easily readable source code.

- You can start using the component immediately without having to come up with its logic from scratch, by using the offered API, which covers around 80–90% of the logic needs for displaying the component, and in most cases, even 100%.

Layered API:

Let’s consider layers using the example of a simple button. On the surface, it may not seem complicated, but here’s how it looks in layers:

- Root

- Inner

- Icon + Left Icon

- Label

- Loader

- Icon + Right Icon

Or, for a more complex component like Select, it can be broken down into layers with the ability to modify the rendering of the dropdown list, etc.

You can create your custom components according to the following rules:

• Styles API
• Default props & types.

Examples of the code can be viewed here.

The impact of Mantine version updates

The skeleton of our project and part of the setup were created using Mantine version 4. We went through the update to version 5 relatively smoothly, and soon we will have to update to version 6. It might be a bit more challenging, but the team has provided a detailed CHANGELOG to help with the process.

Benefits

Mantine is about achieving more results with less effort.

When starting to work on a design system, a lot of time is always invested in basic components, no matter how much we want to avoid it. However, using auxiliary tools significantly eases the work for both developers and designers.

Our very intense development and design phase lasted about one quarter. During this time, 96% of the components were ready, the framework of the application was set up with various providers (authorization, translations, etc.), and several sections related to authentication and onboarding were implemented.

The phase of active synchronization took another quarter. A few new components were introduced (no more than 10), and most of the time was spent on assembling pages.

Currently, we are in the third quarter of development, and I believe we have reached a plateau — there are no major changes happening. However, soon we will begin moving towards design tokens and scaling the design system to other team projects. I think we will go through all three phases of design system development to some extent again.

Summarizing the Definition of a Design System

Let me provide a brief summary and definition of what a design system is.

I’ll start by saying that in my understanding, the ideal start of working on a design system is when passionate individuals from both the front-end development and design sides come together. These individuals are enthusiastic and willing to put in the effort, even staying up late at night to discuss and improve their creation. And there’s a little time to start.

Developing a design system is about:

• Having a single source of truth for UI/UX and interface text.
• Flexibility, standardization, and simplicity.
• Thoughtfulness, efficiency, and transparency.
• Change safety, consistency, and inheritability.
• Automation (not necessarily at the beginning).
• Accessibility.
• Constant communication.

A design system is a set of rules for styling products that helps maintain the integrity of the user experience and optimize resources expended on development and design. It involves a high degree of autonomy through a unified design, component library, guidelines, and established development approaches. This, in turn, allows businesses to simply articulate the problem and what they want to change, while the design system with all its processes and approaches begins to help solve the identified issues.

Ultimately, a design system encompasses:

• Communication rules.
• Visual language.
• Documentation.
• Component library.

I hope this provides an understanding that a UI kit is just a component library, and without all the other elements, it cannot be called a design system.

What a Design System has brought and who it benefits

A design system is not a simple and cheap tool that can be implemented and used casually. A team or company should reach a certain point where the use of this approach is justified.

Let’s take a look at what we ultimately achieved after 3 quarters of working on the design system and product.

• Each team member found value in the design system: costs and feature release speed: By reusing well-designed components, more resources are available for creating new/non-standard features in the product. After laying the foundation, we became faster in designing and assembling application sections.
• Reduction in design time: Using the design system allows designers to reduce the time spent on design and development. This is possible because a significant portion of design elements and components are already ready and can be reused.
• Unified design and components for development: We hardly write styles within the project, thanks to the unified design and components. The proportion of styling files is less than 4%, which speeds up development and the release of new pages exponentially (time to market).
• User interface development is like building with blocks: We spend more time on the application’s logic rather than its layout.
• Single source of truth: Since the design system is the source of truth, there are no discrepancies in interface-related decisions. Any team member can review the design and implementation to ensure compliance with the layout and rules. This helps maintain the quality of released solutions.
• Convenient testing setup: We have design reviews followed by task/feature testing. If there are changes, they are implemented both in Figma and Storybook. For example, our QA team often uses Figma and consults Storybook to review component properties and capabilities. When working with content and editors, we know that most of the product’s textual content is reflected in the design. The text is pulled from a specialized service.
• Product quality: Using the design system allows us to create higher quality products. Strict styling rules, a unified design, and the reuse of elements ensure that the product meets quality standards.
• Developers propose solutions before design: Developers can propose solutions for certain tasks based on established approaches and coordinate them with designers (if the design is not ready yet).
• Onboarding new employees: During onboarding, new employees gain a clear understanding of the capabilities of the components used in the project. They can view interactive examples of their work and read the documentation.
• Unified solution across different projects: There is no need to adapt to a new interface workflow.
• Using a design system helps create a unified design, which enhances the user’s perception of the product. Strict styling rules and the use of a consistent style throughout the project ensure a uniform user interface and make the project more recognizable.
• Fast adaptation to changes: This is more relevant for design, as development becomes more laborious when the API of a component is not compatible with the previous version. The design system allows for quick adaptation to project changes. If changes are made to a component, they automatically apply wherever it is used, which accelerates the adaptation process.
• No bloating of the team’s technical stack: Focus remains on implementing our own UI kit. The product is executed in a unified style, despite consisting of multiple services. There is no need to learn a new framework/version of another library.

The main benefits we gained as a team have been listed above. However, there are certain aspects worth considering, which are not necessarily drawbacks but rather peculiarities:

Synchronizing component changes in Figma and code can be challenging.

Starting a product is more challenging as components need to be developed first before the business begins receiving fully functional application pages incrementally. However, this is true for the first two or three iterations of implementing the UI kit in new projects, as it requires resolving related discrepancies during integration: settings, styling, documentation, versioning, etc. Overall, it is a solvable problem, and with each new project, the startup process accelerates significantly.

Maintaining components as a library is not always easy: versioning and applying new versions to all projects, testing them, etc., can consume a considerable amount of resources. This is especially true at the beginning when requirements can change frequently.

Plans for Design System Development

What’s next? We want to:

• Separate components into a separate package:
• Implement versioning in code.
• Implement versioning in design.
• Start implementing the design system in other team projects:
• Address and resolve related issues.
• Develop new components and improve existing ones.
• Upgrade to version 6 of Mantine.
• Implement design tokens for key components.
• Implement color scheme management.
• Describe standards for component creation and their entire lifecycle.
• Start describing contexts and rules for component usage.

At the time of article publication, some of these tasks will already be completed.

Code Examples

• ESLint configuration
• Styling of the Stats component
• Basic project skeleton (the final solution differs from what is presented in the repository, but the concept is reflected).

This is it! I hope you’ve enjoyed this article. Let me know what you think about it in the comments. I’ll be glad to answer any of your questions. See you!

How design systems are created: sharing our own example. Part 2 was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hello everyone. My name is Dmitry Pashkevich, and I am a frontend developer at Quadcode, specializing in the creation and development of design systems. This article is intended for specialists at various levels who are involved in design systems: from consumers and component developers to team/tech leads building design systems from scratch. Here, I will share my experience, and the path I have taken from creating UI-kits to fully building design systems, and show the benefits that a ready-made design system has brought us. If you are looking to deepen your understanding of design systems, then this article is for you. Have a nice reading!

Intro

To some extent, this combination of words has become a collective term because experience shows that different companies have different interpretations of it. Understanding depends on the maturity level of the team/project/company/processes, the presence of desire, time, and resources, and most importantly, people with “passionate” eyes who will develop this direction despite all the difficulties.

I have gone through the path of creating various UI kits, transforming these UI kits into design systems, to fully building design systems from scratch from the perspective of FE development in the following roles:

1. Consumer of components.
2. Developer of components.
3. Lead in building a design system from scratch. Here, 80–90% of the time was spent on component development, while the remaining 10–20% involved applying components in the product code, as well as sharing knowledge and interacting with the FE development team.
4. Product developer — when you “build components” and immediately implement them during product development. In this case, the entire team participates in working on the design system.

In this article, I want to share the experience we have gained and try to structure it using our company as an example. I will demonstrate the phases of formation and development of the design system that we went through, share the technical stack of our product, and provide insights into the benefits the ready-made design system has brought us.

On one hand, I would like to immediately provide a definition of what a design system is in my understanding, but let’s approach it slightly differently and formulate what comes after the main part.

<SPOILER> For those who are eager to learn the differences between a design system and a UI kit, you can skip ahead to the second part of my article and scroll straight to the section“What is a design system, in summary.” However, I still recommend reading from beginning to end. </SPOILER>

The problems that lead to the emergence of design systems

Firstly, I will start with what usually initiates the birth of a design system. Most often, the reason lies in accumulated and recognized problems that the whole team or specific parts of it begin to address — the areas where the pain is the greatest.

So, what can these problems be?

1. The old design is lost. It is no longer supported, or it exists only in images (yes, it happens). In this case, developers themselves or with the help of a designer come up with ways to incorporate specific elements. The consequence is that the development of new pages becomes a pain. The product inevitably becomes inconsistent across different pages because the logic of interface construction is lost.
2. The old design/interface has become morally outdated, and a redesign is necessary. The question arises: what should be done? Should the current product be modified: modularly, page by page, or should it be built from scratch, etc. — each person chooses their own path. Different paths have nuances that need to be dealt with.
3. Communications regarding feature creation/interface changes exceed reasonable limits. In this case, creating a new element or UX approach becomes disconnected from the product. I think this can be considered as an extension of point 2 and the team’s desire to provide users with a more convenient and modern product.
4. Creating any new feature (even a similar one) takes a lot of time. Various factors can contribute to this, such as poor architecture inherited from the MVP project, outdated tools, or the inability to simply update.
5. The necessity to improve processes. The desire to create a unified point of communication within the team, at least between development and design. A little spoiler: as practice shows, during development, this point, also known as the design system, becomes at least a single source of truth, and discussions constantly arise there.
6. The presence of significant routine work when creating new layouts or coding within a single product. Sometimes, there is no opportunity to reuse a UI kit in design or code. This situation often arises across different projects and occasionally within a single project (more relevant to design in a specific tool). It looks something like this: you open a new design layout, see similar elements but with different names. It becomes difficult for a developer to match elements with the code, and there is a need to standardize everything to avoid wasting time on unnecessary clarification when it’s simply a matter of taking, implementing, and using.
7. There is a product pool within the company, and at some point, there is a need to standardize the UI/UX. Each product has its own team of designers and developers. Does each team need to develop its own UI kit? It happens sometimes. Then the implementation of a design system can start from the design side, which brings everything to a unified appearance. As a result, multiple UI kits may appear in the code due to resistance in different teams, but after a couple of iterations, a unified component base begins to emerge.

These described problems are not listed in any specific order or importance; any of them can be a starting point for creating a design system.

Phases of forming a design system

After realizing some of the above, the process usually begins to create something similar to a UI kit or a large-scale design system. It unfolds as follows:

1. Human and time resources are allocated.
2. Requirements are formed for a technology stack that will meet modern challenges.
3. Based on the requirements, a stack is chosen. The first demo versions of project skeletons appear.
4. Initial agreements between development and design teams emerge — the search for a common language, the desire to synchronize.
5. The core of the design system is born, or it’s more accurate to say, the UI kit, as the processes are yet to be fully formed.
6. The first components are created.
7. The components are tested in the first product feature, and adjustments are made to them.
8. Organic development of components in design and code occurs, with or without design reviews.
9. There is more time for reflection on what has been done and what currently needs adjustment. The development and design teams align their approaches and toolsets to help move forward, including:

• Identifying and resolving issues.
• Introducing new processes (syncs — meetings on how designers create a design, frontend developers work on frontend, QA tests the frontend part of the application, and how everyone interacts with design layouts.
• Implementing new tools.

10. Gradually, there comes a phase where the design system team or individuals responsible for the design system focus less on creating new components and more on assembling pages and maintaining the components.

In this stage of my personal experience related to design system development, I consider this an ideal path to follow. However, there are always nuances, and it depends on the situation.

Phases of design system development

If we delve deeper into this list, the following phases of development can be identified:

Hot phase: This is when components undergo the maximum number of changes in design/code during their implementation into the final product. This phase can last from a few months (on average, 6) to several years. The minimum duration I have experienced is 3 months, and the maximum is 1.5 years. It depends on the initial agreements, the experience within the development team and the business that allocates resources, time, and sets priorities.

The development of components in both code and design occurs simultaneously. There is a connection between development and design, establishing a common language, component naming conventions, and determining the best way to organize the library. Efforts are made to ensure that everything in the design references basic components or that more complex components are built from basic ones.

Many growth points are identified but may not be addressed due to resource limitations or a lack of critical necessity at this stage. These issues are addressed when time becomes available or when it becomes difficult to move forward without resolving them.

The improvement of design system workflows for design and frontend development occurs in parallel. They improve their own processes, and gradually, they start to solve their respective issues.

Sync phase: Shared sync meetings are introduced, such as weekly or sprint meetings, where design and development discuss problems, questions, and suggestions, and agree on small steps to improve their collaboration.

Sometimes, the sync phase can reach a deadlock, where the team starts getting stuck in their own perspectives and needs to share their problems with a third party who is not as deeply immersed in the context. This person can help find solutions more quickly.

Deficiencies in processes related to design review, such as how it is conducted from the design side, what and how they review, are addressed. Critical design changes and priorities are determined. Misalignment between design layouts and compressed release timelines are addressed. Understanding how design processes translate into components in Figma, or vice versa when a design doesn’t know how components are transformed into code, is also resolved.

Plateau phase: Creation of new pages/features/adjustments does not require major rework of key design system components or only involves minimal changes. Major changes in component behavior are possible. For example, rethinking UI/UX when something is found to be inconvenient and needs to be redesigned or when new components with different behaviors need to be introduced. New components are occasionally created.

During the redesign of our product, we went through all these stages of realization and acceptance at a relatively fast pace: we built a working product, not just components, within six months.

I’ll note that all three phases can repeat from time to time depending on the required changes. For example, when separating components into a separate library, adding theme management, establishing stricter component creation standards, or implementing them in a new project.

In the second part of this monumental article, I tell about how to define product requirements and, as a result, design system requirements and also explain why’ve chosen Mantine as a foundation for our own design system. Subscribe and stay tuned! I would be glad to answer any questions in the comments.

How design systems are created: sharing our own example. Part 1. was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hello everyone. My name is Aleksei Burmistrov, and I’m a senior Golang developer at Quadcode. During the billing development, we encountered various types of errors that can occur during program execution. In this article, I want to share our experience in structuring and handling these errors, as well as present the approaches we applied for their efficient handling and diagnostics. Our main goal is to create understandable and easily manageable errors that guarantee reliable billing system operation.

Errors are one of the most important aspects of any programming language. How errors are handled affects applications in many ways. The way errors are defined in Golang differs slightly from languages like Java, Python, and JavaScript. In Go, errors are values.

Custom Error Type

All error-related code is placed at the root of our project. This is done to prevent conflicts with the standard errors package. Such an approach makes error handling in the application more explicit and allows us to use the standard library without applying aliases.

The foundation of it all is the Error type, which is a specific representation of an error that implements the standard error interface. It has several fields, some of which may not be set:

type errorCode string

// Application error codes.
const (
    ENOTFOUND errorCode = "not_found"
    EINTERNAL errorCode = "internal"
    // Add other error codes here
)

type Error struct {
    // Nested error
    Err error `json:"err"`
    // Additional error context
    Fields map[string]interface{}
    // Error code
    Code errorCode `json:"code"`
    // User-friendly error message
    Message string `json:"message"`
    // Executed operation
    Op string `json:"op"`
}

• Op represents the operation being performed. It is a string that contains the name of a method or function, such as repo.User, convert, Auth.Login, and so on.
• Message contains the error message or translation key that can be shown to the user.
• Code is a specific error type. It provides standardization and unambiguous error handling, allowing easy identification and classification of errors. The list of possible codes can be extended as needed, providing flexibility and the ability to add new error types as the application evolves. It also allows us to accurately define API response statuses associated with each error type.
• Fields represents data related to the error. This data can include identifiers, request parameters, or any other information that may be useful for understanding the cause of the error.
• Err contains a nested error, which may be associated with the current error. It can be an error returned by an external library or our own Error. Having a nested error is useful for tracking error chains and building a trace, which we will discuss later.

Creating an Error

To create an error, we decided not to have a separate constructor since the structure is not too complex. To ensure that developers don’t make mistakes when creating an error (e.g., forgetting & or creating an error without Err and Message), we use our own linter for golangci-lint.

Let’s consider an example. In normal usage, we may return an error multiple times within a method. To handle this, we define a constant, conventionally called op, which will be passed to all errors in the method:

func (r *userRepository) User(ctx context.Context, id int) (*User, error) {
    const op = "userRepository.User"
    ...
}

If we only need to add op to the error for passing it to the higher level, we can use the helper functions OpError or OpErrorOrNil.

...
var user User
err := db.QueryRow(ctx, query, id)
if err != nil {
    if errors.Is(err, pgx.ErrNoRows) {
        return nil, &app.Error{Op: op, Code: app.ENOTFOUND, Message: "user not found"}
    }
    return app.OpError(op, err)
}
...

Error Handling

The advantage of using our custom error type is the ease with which we could write error-dependent tests and write error-sensitive code outside of tests.

To check the Code, there is a helper function called ErrorCode that returns the error code if it is an application error, or EINTERNAL if it is something else.

switch ErrorCode(err) {
    case ENOTFOUND:
    ...
    case EINTERNAL:
    ...
}

If we need full access to the Error struct, we can use the standard library errors.

appErr := &Error{}
if errors.As(err, appErr) {
  ...
}

Using the Code field allows for clear conversion of errors to HTTP statuses. To achieve this, we can create a map where the keys are Code values, and the values are the corresponding HTTP statuses.

Example of converting an error to an HTTP status:

var codeToHTTPStatusMap = map[errorCode]int{
    ENOTFOUND: http.StatusNotFound,
    EINTERNAL: http.StatusInternalServerError,
    // Other mappings of error codes and HTTP statuses
}

func ErrCodeToHTTPStatus(err error) int {
    code := ErrorCode(err)
    if v, ok := codeToHTTPStatusMap[code]; ok {
        return v
    }

    // Return the default HTTP status for unknown errors
    return http.StatusInternalServerError
}

Now, to get the corresponding HTTP status for an error, simply call the ErrCodeToHTTPStatus function and pass the error to it. It will return the appropriate HTTP status. If the error code is not found, the default HTTP status http.StatusInternalServerError will be returned.

Analysis and Diagnostics

When analyzing errors in our application, we rely on the information we log. However, when errors are logged as strings, it makes it difficult to search and analyze them. To address this, we structure our logs for sending them to Graylog, logging errors as objects that contain the following information:

• code: The error type to understand its nature.
• msg: The message from Error.Error().
• fields: Additional context added to the error.
• trace: The stack trace of operations.

In our logs, we avoid logging the standard stack trace for application errors because it provides too much information and makes analysis difficult. Here’s an example of a typical stack trace:

goroutine 1 [running]:
testing.(*InternalExample).processRunResult(0xc000187aa8, {0x0, 0x0}, 0x0?, 0x0, {0x1043760e0, 0x1043b8d88})
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/testing/example.go:91 +0x45c
testing.runExample.func2()
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/testing/run_example.go:59 +0x14c
panic({0x1043760e0, 0x1043b8d88})
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/runtime/panic.go:890 +0x258
app.foo(...)
       app/errors_test.go:336
app.bar()
       app/errors_test.go:341 +0x38
app.baz()
       app/errors_test.go:345 +0x24
app.ExampleTrace()
       app/errors_test.go:350 +0x24
testing.runExample({{0x1042f8cd5, 0xc}, 0x1043b8528, {0x1042fcab9, 0x19}, 0x0})
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/testing/run_example.go:63 +0x2ec
testing.runExamples(0xc000187e00, {0x10450e080, 0x1, 0x0?})
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/testing/example.go:44 +0x1ec
testing.(*M).Run(0xc00014a320)
       /opt/homebrew/Cellar/go/1.19.4/libexec/src/testing/testing.go:1728 +0x934
main.main()

In this case, there is a lot of redundant information that is difficult to analyze. However, the stack trace of operations looks like this:

["ExampleRun", "baz", "bar", "foo"]

The operation stack trace is easily readable and contains only the domain logic, which is important for us.

For logging errors, we use the go.uber.org/zap package. We have created a helper function called Error(err error) zap.Field, which allows us to easily log errors as objects.

Here’s an example of using this function:

func foo() {
    ...
    if err != nil {
        logger.Error("something gone wrong", Error(err))
    }
}

An example of the error logged in the log could look like this:

{"level":"error","msg":"something gone wrong","error":{"msg":"user not found","code":"not_found","trace":["userRepository.User"],"fields":{"user_id":"65535"}}}

Final Thoughts

In Golang, we have complete freedom in choosing how to handle errors in our applications. However, with this freedom comes great responsibility, as proper error handling plays a crucial role in ensuring the reliable operation of an application. It is important to understand that each application has its own specific requirements, and we can modify error handling accordingly based on those requirements and context.

We have the flexibility to manage the data contained in the Error structure and modify it according to our needs. We can make adjustments, add additional data and functionality to improve error traceability and analysis.

If you want to see code examples, you can find them at https://github.com/MrEhbr/app.

Proper error handling is an important component of application development, and we should constantly strive to improve our approach to error handling and analysis to ensure more reliable and convenient application operation.

How to Handle Errors in Golang — Sharing Our Own Use Case was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

One such tool that I will be introducing to you in this article is the classification of personality psychological types, also known as personality cores. I will focus in more detail on one of the psychotypes that has a sensitive or, as it is also called, a depressive core. People of this psychotype often prefer the HR sphere and working with people, for example, in customer service and sales.

Let me clarify right away that there are no good or bad psychotypes. Their diversity is created to perform different functions in human population life and to fulfill their unique roles.

Realizing one’s psychotype opens up the opportunity to more accurately define one’s needs, as well as to shape one’s psychological portrait and understanding of “who I am”. Identifying strengths and weaknesses allows a person to see themselves as clear as day; not to change, not to escape, not to deny their personality, but to accept and develop their potential, activating their development.

Knowledge of psychotypes helps us to understand other people better, to be more tolerant of their peculiarities and, as a result, to communicate with them more successfully and effectively.

What is the Personality Core?

The psychotype serves as a unique foundation of personality, its core, representing a set of individual characteristics that are largely formed in childhood.

People with different psychotypes differ quite sharply from each other: they relate to themselves and to others differently, and each has their own way of speaking. Everyone works, creates and fantasies differently, commits different acts and suffers from different illnesses.

The core is similar in meaning to temperament, including emotional, behavioral, and rational reactions. For example, one person might be pleasantly surprised by an unexpected gift, while another might be neutral: “Yes, thank you. Wonderful”.

In addition to the main personality core, there are also additional ones, which are formed because a child is usually raised by more than one person. This is not necessarily a mother and father; it could be a mother and grandmother, father and kindergarten teacher, and other people involved in the child’s life at that time.

Each core has its own shadow sides. These are the aspects that a person can develop and improve within themselves.

Types of Personality Cores

A person’s core can be determined in communication. For someone who knows the characteristics of each psychotype, an hour is enough to determine the main core of their interlocutor.

There are dozens of classifications of personality core types or psychotypes. Different psychological schools use different classifications. For example, Carl Jung identified 8 psychotypes, while Soviet psychiatrist Andrey Lichko identified 13.

I use a simplified classification in my work, as simplicity and efficiency are important to me. I have identified six main psychotypes for myself:

1. Narcissist.
2. Hysteroid.
3. Schizoid.
4. Paranoid.
5. Epileptoid.
6. Sensitive (depressive) type.

Let’s examine the characteristics of each psychotype according to this simplified classification: who these people are, what to pay attention to, and what to consider when interacting with them, as well as their strengths and weaknesses.

Narcissists

Narcissists are charming and charismatic people, self-absorbed, striving for perfection, and possessing a creative personality. They have a need to be the center of attention and painfully perceive negative evaluations from those around them.

People with a narcissistic core have a high level of communication, sufficient empathy, and can make others fall in love with them. They quickly become excited about ideas, can quickly find support, and inspire others. In business, a narcissistic leader is likely to have an inspired and motivated team.

Narcissists give beautiful and careful compliments. Moreover, they genuinely believe in what they say. They can notice the beauty not only in themselves but also in the outside world, it is natural for narcissists. Narcissists need to receive approval and confirmation of their successes, and they seek it in other people. It is not enough for a person with a narcissistic psychotype to wake up in the morning and tell themselves, “How wonderful I am”. They need others to do it for them, they need a “mirror” that will respond, “Everything is great with you/you’re doing a great job.”

If you want to achieve something with a person of this psychotype, you need to praise their work and achievements. In turn, narcissists will not say directly, “You did a bad job,” but will use phrases like, “A specialist of your level is capable of more.” This is not a direct reproach, but it can hurt.

An example of a narcissistic psychotype from literature and cinema is Jay Gatsby from “The Great Gatsby”.

Hysteroids

Many scientists and practitioners use this concept, not referring to a “hysterical” person, but speaking about a type whose core is focused “inward” and on gaining attention through self-focus. Unlike narcissists, hysteroids are more self-sufficient and stable in terms of self-esteem.

This type is capable of transforming according to the situation, changing roles and playing them with dignity. Hysteroids are confident in themselves and find it difficult to accept the fact that someone else might also want to be on the “stage” with them. They may dress brightly and unconventionally. The opinions of others don’t bother them much, so they can afford to “put on a show.” If a narcissist opens the door and says, “Good day to everyone, my dears!”, a hysteroid is quite capable of kicking the door with the phrase, “Hey, dudes!”

A hysteroid leader will draw attention to themselves. Therefore, people with this psychotype are often lone heroes. The shadow side of hysteroids is that they can be insensitive. They may express themselves loudly, shout, interrupt. For them, it’s a kind of game, their image. At meetings, you can spot hysteroids by the fact that they “take” the microphone and talk about themselves for a relatively long time.

An example of this psychological type in cinema is Ruby Rhod from “The Fifth Element”.

Schizoids

The schizoid psychotype is about the deep inner world, mental processes, logical chains, high concentration, focus, and a new perspective on the world at a super angle, which can be extremely inconvenient for other types. Again, I emphasize that the name of the psychotype does not mean that a person is schizophrenic or similar.

Schizoids are about measured pace and deep thoughts. They see details and patterns that others do not notice, ask atypical questions, and help to look beyond the usual worldview.

Schizoids are characterized by introversion. They get tired of people, and can take a long time to respond, not because they don’t want to, but because they can’t find the strength or don’t see the significance in the message. People for them are elements. At the same time, it is not uncommon for a person to have a combination of a hysteroid and a schizoid. They can, for example, give a scientific presentation to a large audience, and then retreat and sit in his cage.

An example of a schizoid is Sheldon Cooper from the TV series “The Big Bang Theory”.

Paranoids

A paranoid type is a projectile with great penetration power. Energetic, never doubting their correctness and the incorrectness of all who hesitate.

In ordinary life, this is just a purposeful and self-confident person who knows what they need. If they have a super idea, they go straight through to it, sweeping away everything in their path and not paying attention to small things, details, and even people.

It is very difficult to determine paranoids; they are peculiar “chameleons.” They can camouflage while pursuing their goal: not showing themselves at the beginning, and then switch to radical actions.

Among the pros, these are very powerful people. They can survive and rise from the ashes. They have immense inner confidence. Paranoids create ideas that others will follow. They have charisma, the ability to sell their vision at a rational level, and convey meanings.

For the sake of the goal, paranoids are ready to step on heads, regardless of the emotions of other people, discussing plans behind others backs. They can make very tough decisions in the name of achieving results: “We need to cut costs. We’re firing 500 people.” — “We only have 50 left…” — “It doesn’t matter. We’re going for the goal.”

The name of the psychotype itself comes from the constant paranoia of its representatives. They are worried that someone will know more and not share information. Paranoids want to be involved in everything, but at the same time, they will give little in return.

An example of a paranoid from literature is Dolores Umbridge from “Harry Potter”.

Epileptoids

Let’s not confuse epileptoid with epileptic. We are discussing all psychotypes within the norm.

Reasonable, thrifty, sociable. Epileptoid thinking is pragmatic, clear, and understandable to all people. They structure their statements well, breaking them down into simple phrases. They do not overuse introductory sentences and participial phrases, nor do they ponder on high philosophical categories.

Their logic is consistent and simple. However, an epileptoid, like a paranoid, can twist logic with borrowed arguments.

Epileptoids are people who follow an idea or authority. They are characterized by a strong attachment: if they believe in someone or something, it will be extremely difficult to persuade them otherwise. They are also very systematic, consistent, and structured. Epileptoids feel comfortable working according to a built process, adhering to regulations. They can deviate from the rules if the leader confirms that it is necessary. In general, epileptoids have the principles of “must’’ and “necessary.”

People with this core are loyal, devoted, and responsive, but in their work, they have minimal flexibility. Because of this, it can be difficult to communicate with epileptoids. They find it hard to be fast and break their usual routine. However, they are well suited for monotonous work or companies with pronounced bureaucracy.

In the movies, an example of such a psychotype is Desmond Doss from the film “Hacksaw Ridge”.

Sensitive (Depressive) Type

Narcissists are interested in beauty, aesthetics, and the sublime. Hysteroids focus on their own “self.” Epileptoids are focused on processes. Schizoids explore how things work. Paranoids concentrate on a certain ideology. Only sensitive types have a significant focus on people. More often, this type serves as an addition to the main personality core.

This psychotype is characterized by excessive sensitivity, impressionability, high moral demands primarily on oneself, low self-esteem, shyness, and timidity. Under the blows of fate, people with a sensitive core easily become extremely cautious, suspicious, and withdrawn, so they are vigilant and watch the reactions of others. Such people are diligent and devoted. They can show kindness and mutual assistance, be very sociable and communicative. Social recognition is important to them. They have predominantly intellectual and aesthetic interests.

The sensitive core is more focused on others than other types: people with this psychotype are altruists, volunteers, HR managers, psychologists, and psychiatrists. They inspire trust because sensitive types usually have a kind and attentive facial expression.

From this comes the advantages of the sensitive core — the ability to feel another person, empathize, and help. These are the people with unconditional acceptance: everyone is good, everyone has rights, and they have the right to be who they are now. The sensitive core feels the need to catch up with others and help them. Therefore, for people in HR teams, hard skills are their soft skills.

One of the characteristics of this psychotype is that a person with a sensitive core may become depressed. Not in a clinical sense, but in losing their identity without others and forgetting to take care of themselves. Sensitive people tend to engage in self-digging. They often think, “What will people think of me? How do I look? I need to help. I can’t help but help.” However, such self-digging is not always productive and can lead to a state of permanent sadness.

An example of a character with a sensitive type is Amélie from the movie “Amélie”.

How a sensitive type can support themselves

When a person wants to help everyone, be friends with everyone, and listen to everyone, the question arises: how can they support themselves? In my examples, I will consider working in an HR team because, in business, the sensitive core is most often encountered in such positions.

There are three main support scenarios, and they complement each other:

1. Reflection and self-development.
2. Support from a specialist.
3. Help from the team.

Reflection and self-development

It is important for a person with a sensitive core to learn to realize and accept that they need to take care of themselves in order not to fall into despair and not to be morally exhausted. Therefore, it is worth starting with reflection, gradually turning it into a productive direction. Specialized literature can help with this, for example, “Emotional Intelligence: Why It Can Mean More Than IQ” by Daniel Goleman.

Support from a specialist

I think you’ve heard that every psychotherapist has their own psychotherapist. This is pure truth: mature specialists always have a supervisor. This can be a psychologist, psychiatrist, coach, or mentor. For a person with a depressive core, such support is truly useful and necessary, so do not hesitate to seek external help.

Help from the team

In our BP team, we practice team meetings with case analysis, where everyone can share their difficult tasks and ask for advice on how to act in a specific situation. Teamwork is essential because it impartially assesses the situation, which helps to get recommendations for interaction, and also raises rational questions that reduce the emotional level towards a particular case.

Team supervision provides a sensitive person with more algorithms for solving various cases. This allows them to make decisions not based on an emotional surge, but with a clear understanding of why a particular action is needed.

I recommend holding general supervision meetings for HR employees at least once a week. There are many different tasks in this position, and such regularity is optimal. Even if there is nothing to say at the moment, it is still worth attending general meetings. Supervision greatly enriches and fills with experience and practice. You listen to what others are solving and think, “I had such a situation. I suffered all weekend, thinking about George to whom I said something wrong.” And a colleague’s decision, different from yours, expands variability and develops thinking not only in terms of human interaction but also in terms of business context.

In my experience, the optimal number of supervision participants is 4–5 people. Then everyone has the opportunity to speak if necessary, but there is no overload of opinions. When 10 people ask their questions and offer solutions, you easily forget what the first person said.

At Quadcode, we don’t have a fixed team supervision protocol. Whoever has a request speaks up. The importance of the case and the desire to hear opinions from others are crucial. If I don’t want to tell or listen, nothing will work.

Anonymity is also essential. Supervision participants should not share what happens during the session. As an HR team, we provide this guarantee to our colleagues. You can generally avoid mentioning specific names when discussing a case; this is also a workable scenario. Another critical element is being non-judgmental. Opinions should only be expressed through a personal point of view: not “you are wrong,” but “it seems to me that you did something wrong.”

I can also recommend using the emotional waterfall technique at meetings. You may have noticed in life that when something happens, you want to call everyone and tell them everything. But after a certain number of calls, everything sounds less emotional. The first listeners get the maximum amount of details and vivid emotions, while the fifth gets: “Here’s the story. They hurt me. But I figured it out.” This is the waterfall effect, which helps to reduce the emotional response and switch to rational thinking.

If the first waterfall occurs in a safe environment for the employee and among those who listen, it is beneficial and reduces burnout. HR burnout is directly related to emotionality and overloading. If you can relieve the first wave, exhale, and think rationally, it becomes easier. It is also helpful to conduct a mini-retrospective with colleagues — what you did right and what you can do more. This helps to stabilize and expand the variability of future decisions.

In terms of supervising moderation, I would base it on the HR team itself. How self-organized and mature is it? If we have young HRs with little experience, it is worth involving an external moderator: an outsider or a manager with greater facilitation competencies.

In conclusion

I believe that understanding and recognizing one’s own psychotype and the psychotypes of others is the key to successful and comfortable communication. Don’t be afraid of your peculiarities or the peculiarities of others, as they help us look at situations from different angles and find the best solutions in life and business.

The Core of Personality: Strengths and Weaknesses of Different Types was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.

My name is Olya, and for 5 years I’ve been developing an employer’s brand in IT. Today I want to share my vision of how to better organize this process.

Types of Company Brands

A company’s brand most often works for two key audiences:

• A Product/Business brand is when a brand works with customers and communicates to them the value of your product/service.
• An employer’s brand is when a brand works with current/potential employees and communicates to them the value that you’re an excellent employer.

The brand can also help promote the image of the company among potential investors, the government, Martians — the specifics of the audience will influence the strategy. But the set of tools will be similar: articles, videos, events, etc.

Bottom line: no matter what brand you decide to develop from scratch because the tools for its promotion are identical. And the steps below will help you structure your brand building.

How to Build a Brand: a Manual

Method #1: Launching MVP

If you need to do it quickly, inexpensively, and you can turn a blind eye to the quality, then I suggest starting with the MVP — the minimum version of the product sufficient to test the idea. Suddenly no one wants your brand, and you’ve already hired a staff of brand managers and gone broke on salaries.

MVP Recipe:

• Choose 2 of your favorite colors.
• Use templates to create the first layouts in your colors for example via Canva.
• Come up with a slogan. Take your favorite 5–7 slogans, mix them up, and add your brand name. Voilà!
• Create a profile on one of the social networks.
• Fill out the profile with 5–7 posts. Images can be found on photo stocks or taken with a phone. Or you can delegate both visual and text creation to neural networks. For example, use Photoleap app for images and ChatGPT for texts.
• Let your heart guide you in setting your target. If there’s no money for it, then let all employees, their friends, and relatives make reposts.
• Collect the reaction and the first results.

Of the advantages: I think that in a week, you can get the first feedback and understand how to move forward. This is the fastest way for a brand to make itself known.

Of the minuses: it’s difficult to talk here about a positive impression of a brand created “quick and dirty” using whatever is available and of attracting target customers; it’s a rather risky bet.

Method #2: Going Strategic

If you want to approach a brand launch in a more deliberate and high-quality way, then set aside time and money. A brand, in general, is an ephemeral thing. You invest in it, but it’s almost impossible to know for sure if they bought your loaf of bread because they trust the brand or because you put up a discount. This is the magic of superior branding knowledge; I myself am still in search of an ironclad formula.

Let’s start with self (brand) awareness. At the first stage, it’s important to understand what kind of brand you are, how you’re already perceived, and at what point you want to arrive. Research will help with this.

I’m going to talk about the employer brand, but you can also try this approach on product strategies.

Step 1 — internal research

• In-depth interviews with top management/HR/marketing.

I calculate the time taking into account the fact that you’re the only brand manager, and you still have other tasks.

Approximate time: 2 weeks (15 interviews).

The purpose of the interview is to create a starting point and formulate measurable expectations of the result.

Sample questions:

● How many times in the last month have you encountered the need for a strong employer brand?

● Why is brand development important to you?

● How would you formulate the first steps that will help the company build a strong employer brand?

If you want to take a ready-made workflow and look more impressive in the eyes of your colleagues, here’s a link to examples of from CustDev questions that can easily be adapted to the task at hand.

Step 2 — analysis of competitors

Make a list of actual and desired competitors. For example, you really like the respectable Google, and you put it in the competition column. But! Check how comparable your sales volumes, budgets, and media weight are. If these indicators of your company are still far from Google, it’s better to remove Google from the list of competitors (at least in the first year of brand development).

The key idea: choose those competitors who you have enough current budget to compete with and to whom your audience is already going.

Next, prepare criteria for comparing competitors. For example, in my projects for employer brands, it can be: the frequency of mentions in the media, the number of employees, EVP (employer value proposition), the number of external channels, the number of events, the number of reviews and their quality, etc.

Approximate time: 1 week (7 competitors).

Formats for analysis:

• The good ol’ Excel spreadsheet where you enter all your competitors and compare them by common criteria.

And for fans of fashionable frameworks:

• Censydiam.
• Mapping competitors.

Step 3 — study the target audience

At this stage it’s important to specify concretely a portrait of your target audience (TA). This is where heart-to-heart conversations and in-depth interviews with the TA will help you.

Approximate time: 1.5 weeks (20 interviews).

Goal: To understand the customer/user/employee path (CJM — Customer Journey Mapping) and audience demand.

Sample questions:

• How did you find your last job?
• Have you been in contact with any no-name companies?
• How would you rate our site/social network on a 10-point scale?

For a link to other CusDev questions, see step 1.

Then you need to analyze the answers and break them down into 2–3 key blocks.

For example, in the course of your research, your respondents often mentioned corporate events and their attitude toward them. Collect their quotes related to corporate parties and suggest a heading that would combine similar quotes. In our case, the target audience’s quotes were well illustrated and unified by the heading: Corporate parties are great, but you can’t attach them to a resume.

Step 4 — formation of the concept

The research has been completed, and a lot of material has been accumulated. The next goal is to choose a concept that meets the demands of the TA and the business.

To do this, you need to understand the data and identify the most common responses from the TA, competitors, and stakeholders. Next, you need to generate a Reason to Believe (RTB) list of benefits of your brand. RTB can be divided into emotional (for example: we build technologies of the future) and rational (for example: we give all employees the latest models of tech equipment).

After that, you need to strengthen communication with insight and hypothesis, which will further help you build a creative campaign. Simply put, without academic chic, insight is a situation close to the consumer, which contains some actual problems for them (more info here). A hypothesis is an assumption about the target audience that can be confirmed or refuted during the research (more info here).

I gave an example in the table.

This is NOT rocket science. If you need me to describe this item in more detail, then write to me in the comments, and I’ll talk about it in a separate piece.

Step 5 — formation of a communication strategy

This is where you need to bring a copywriter on board to help create a strategy and maintain further communication.

You need to show the copywriter:

• Conception.
• RTB.
• Competitor analysis

Next, you need to form a clear task for the creation of a communication strategy and content plan for various platforms (social networks, blog, website), audiences, etc.

Approximate time of creative flight and analysis: 2 weeks.

Participants: brand manager, copywriter, creator/art director, outstanding representatives of TA for joint brainstorming.

Step 6 — create a corporate identity

Recall what has already been done before, add a little, and take it to the designer:

1. Competitor analysis.
2. Brand positioning (audience description + hypothesis/insight + RTB + communication strategy and content plan).
3. Visual references.
4. A list of platforms/formats that need to be branded.

Approximate time: 2–3 weeks (along with discussions, approvals).

Remember that, in general, the brand, text, design are very subjective things, so coordination and testing can be delayed considerably. But all the work done above just allows you to rely on the data and translate doubts into a constructive channel.

Step 7 — launching a brand platform

Congratulations! You’ve done a great job, and now it’s time to go out into the world.

What might the timing be for launching a brand from scratch?

• In the first month, launch the main channels of communication, such as the landing page and the social network. We drive traffic to them and collect feedback.
• After a quarter, if necessary, we edit the brand strategy and launch additional channels, testing new formats to increase the number of contacts with the audience. This is called activation of the brand platform, it has a lot of its own nuances for a separate article.

What We Ended up with

In the article, I briefly described the structure and steps to help you build a brand from scratch. If you’d like to know more about any of the steps, then let me know, and I’ll try to respond in a new article. And if you have a more specific question, then write to me on LinkedIn.

How to Build an Employer’s Brand from Scratch was originally published in Quadcode on Medium, where people are continuing the conversation by highlighting and responding to this story.