DEV Community: Mikhail Panichev

Git Playbook: Team-sync and Stable Releases

Mikhail Panichev — Fri, 21 Aug 2026 10:22:49 +0000

This article describes a Git methodology that I developed managing software development.

I successfully applied these approaches in different kinds of teams: cross-functional, product-based, and outsourcing teams. Team sizes ranged from three to twenty people.

Main benefits and problems it solves:

Stable releases and stable master.
Reducing risks by stabilizing the code that gets merged into master right before a release.
Synchronizing Git with planning.
Changes in Git are explicitly linked to issues in the issue tracker. This makes it easy to find the reason behind any change in the code history and makes releases more predictable.
Synchronizing Git with deployment.
A clear link between the Git history, build artifacts, and production instance tags simplifies incident management.
A branching canonical Git history.
The history graph gives you overview the current state of development or the cost of a project without using time tracking.

Abstract

The process is built on the feature branch workflow: the master branch is always stable, and there is one branch per task.

Releases use tags created from the master branch. Tags are named using SemVer.

To keep master stable, Release Candidate (RC) branches are used. All the changes that are going to be released live in the current RC branch. RC branches go through a stabilization phase before being merged into master.

The branch for the next release, like every other branch, is always created from the up-to-date master. The team always works with the latest version of the code.

Changes for an individual task are not merged into master directly but through the RC branch. For code review, a Merge Request (MR) is created from the task branch into master. Each MR is closed automatically when the Release Candidate is merged into master.

If needed, you can also apply the green trunk practice. When several tasks share code that does not affect users, it can be merged directly into master, bypassing the release cycle. Such situations should be treated as exceptions and require extra control over the changes being merged.

Prerequisites

Besides the requirements described below, CI/CD automation is implied. However, the lack of automation does not prevent you from adopting the process.

It is recommended to have the following pipelines in CI/CD:

automatic builds of fixed environments from their corresponding branches;
automatic build of an environment for an individual task on demand;
running static code analyzers and automated tests in the MRs of individual tasks.

Issue tracker

Since the process relies on a close link between the change history and planning, you need an issue tracker that automatically creates a short, human-readable identifier for each task or issue.

Common trackers such as Jira or YouTrack provide a short auto-increment task ID out of the box.

You can also use the Issues functionality in GitHub, GitLab, or Gitea. In that case, you can use either the local or the global issue identifier for the branch name (for example, 42 or acme/service#42).

Tools like Trello, Asana, or Notion probably won't fit the process, because they don't generate a readable unique ID for a task.

Testing process

The methodology gives you flexibility in how you organize the testing process.

The most important thing is testing the release branch. This step cannot be skipped. When you test the release branch (or release candidate, RC), you stabilize the code that will end up in master and, later, in production.

Besides release testing, you can also test a task in isolation or use a shared test environment. The table below lists all the possible environments for testing.

Environment	Description
`<issue_id>`	Environments for testing an individual task in isolation. + No false-positives caused by overlaps with other tasks. - Extra requirements for server resources and infrastructure that can automate environment creation (for example k8s or Coolify).
`test`	A shared test environment, the least stable one. + Cheap and simple to set up. + Convenient for getting quick feedback. - Problematic changes can break the test environment for everyone on the team. - It can drift significantly out of sync with `master` — in that case, you simply recreate the environment.
`stage`	The code of the last release with test dependencies. Can be used to debug production issues on test data.
`rc-<version>` or `rc`	An environment for testing the changes that go into the next release. It must be used during development.

The release process

First, you put together the list of tasks that go into the release. The selected tasks must meet the following requirements:

The code has passed review in the Merge Request (MR) for that task.
The MR has no conflicts with master.
The changes for the individual task have been tested.

Based on the task list and following SemVer (Semantic Versioning), you determine the number of the next version. Using that version number, you create a new Release Candidate (RC) branch named rc-* (for example, rc-v1.5.24).

With the task list and the next version number in hand, you can create a release entity (explicitly or just as a parent task). This step is optional, but it improves the connection between the tracker and Git.

The release branch rc-* is created from the up-to-date master. It is best to explicitly sync master before creating the release branch:

git checkout master

git pull

git checkout -b rc-<next_version>

When the RC branch is created, you go through the task list and merge each task one by one. If merge conflicts come up, you resolve them on the spot, in the RC branch. After merging the branches of all required tasks, you sync the RC branch with the remote repository.

git merge ABC-42

git merge ABC-73

git push -u origin rc-<next_version>

The next step is stabilizing the release. You test the release on a fixed or dynamic environment. If you find problems, they should be fixed in the branch of the corresponding task and then merged into the RC again.

There may be cases where a fix cannot be tied to any specific task. In such cases, it is acceptable to make changes directly in the RC branch.

Once the RC branch is stable, the changes can be merged into master. At the moment of the merge, all MRs of the release's tasks are closed automatically.

git checkout master

git merge rc-<next_version>

git push

Immediately or some time later, a new tag is created from master. The tag name is used as a key in the project's build artifacts, for example in Docker image tags.

git tag -a "<next_version>" -m "<next_version>"

git push && git push --tags

Deploying the artifacts linked to the Git history is done automatically in CI/CD or manually.

The target change history

The diagram below shows an example of a Git commit graph between two releases. The example reflects the main ideas: asynchronous work in feature branches and stabilizing the RC branch before merging into master.

Open in mermaid.live.

Git configuration

Every developer should have the following lines in their ~/.gitconfig file:

[merge]
    ff = false
[pull]
    rebase = true

Disabling fast-forwarding merge is used to maintain the canonical structure of the history.
Automatically using rebase on pull helps avoid "loops" in the history when you fetch changes from the remote repository that differ from your local ones.

A Git hook for commit messages

Having a link to the task in the commit message makes investigating the reasons behind changes with git blame much easier. After a few releases, a single commit gets many parent branches, and it becomes hard to find the original one.

An issue identifier in the commit message links every line of code to a specific task.

To avoid mistakes and forgetting to reference tasks, this should be automated.

Here is an example .git/hooks/prepare-commit-message script that adds an issue reference to the commit message:

#!/bin/bash

COMMIT_MSG_FILE="$1"
COMMIT_SOURCE="${2:-}"

BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)

if [[ -z "$BRANCH_NAME" || "$BRANCH_NAME" == "HEAD" ]]; then
  exit 0
fi

PREFIX="$BRANCH_NAME"

if [[ "$BRANCH_NAME" =~ ^[0-9]+$ ]]; then
  PREFIX="#$BRANCH_NAME"
fi

FIRST_LINE=$(head -n1 "$COMMIT_MSG_FILE")

if [[ "$FIRST_LINE" == "$PREFIX "* ]]; then
  exit 0
fi

sed -i.bak -e "1s|^|$PREFIX - |" "$COMMIT_MSG_FILE"

Git working rules

Commits
- Commits should be as atomic as possible. ¹
- Many small commits are better than one big one.
- A commit message should describe the changes it contains.
- A commit message should contain a link to the issue. ²
- In a task branch, it is acceptable to commit and push non-working code marked with WIP (Work In Progress).
- It is preferred to keep WIP commits in the history. ³
Creating feature branches
- Each task gets a unique branch for making changes.
- A task branch is always created only from the up-to-date master.
- The branch name should exactly match the task identifier in the tracker. ⁴
- Several developers can work on the same task branch at the same time.
- If the same new code is needed in two different task branches, it is preferred to use git cherry-pick or to push the shared code through the release cycle.
- It is not allowed to merge task branches into each other.
Merging branches
- git merge is always used to merge branches.
- Merging branches must create a merge commit.
- When merging branches, all previously created commits stay in the history unchanged (forever).
Merge Requests
- Before changes from a task branch are integrated into master, a Merge Request (MR) must be created.
- Before a task gets into the release build, the code must pass review.
- If an MR has conflicts with master, they must be resolved by merging master into the task branch. ⁵
Integrating into master
- Changes from feature branches get into master through Release Candidate (RC) branches.
- It is acceptable to make changes directly in the RC branch. ⁶

Translated from Russian original.

A good time to create a commit is when you finish a separate logical block of work. It is implied that a single commit can be rolled back with git revert or moved to another branch with git cherry-pick. ↩
Adding the issue reference should be automated with a Git hook. ↩
Squashing commits and other history rewriting while working in a task branch is acceptable when the following conditions are met: (1) no more than one developer works in the task branch; (2) the branch has not been merged into any other; (3) no other branches have been merged into it. To avoid problems with the Git state, it is better not to rewrite the commit history. ↩
It is preferred to limit the branch name to just the task identifier and not use feature, fix prefixes or a description suffix. Unlike the identifier, such prefixes and suffixes are subjective. ↩
To resolve conflicts, you need to sync with the up-to-date master, then run git merge master in the task branch and resolve the conflicts if needed. This will create a merge commit from master into the task branch. If there are conflicts with master, the task cannot be included in the release build. ↩
In Release Candidate branches it is acceptable to make changes that are not tied to any specific task. This can be meta-information changes (changelog, package version) or fixing hidden integration conflicts between two different task branches. ↩

How to Build a Home Cloud with Proxmox

Mikhail Panichev — Fri, 27 Feb 2026 23:07:30 +0000

One day, I realized I wanted a home server to experiment with deployment and infrastructure. Posts on r/homelab and r/selfhosted largely inspired this idea.

At first, I considered going the bare-metal route and building a k3s cluster on several Raspberry Pis. However, after comparing costs, limitations, and capabilities, I decided to buy a couple of Lenovo ThinkCentre mini PCs and install Proxmox Virtual Environment (PVE) on them.

At work I’ve actively used cloud providers, so it was important for me to have a user-friendly experience with virtual servers — similar to what a compute cloud offers.

Key requirements for the virtualization infrastructure:

VMs may be on an isolated network, inaccessible from the home network;
easy creation of a Debian server with cloud-init;
server management via Terraform.

After spending several days searching online, tweaking configs, and reinstalling everything from scratch a couple of times, I came up with a working solution and identified some pitfalls.

Preparing a Private Network

I decided to ensure basic security by placing virtual servers on a network separate from other devices.

Instead of spending time on VLANs, complex routing, and firewalls, I used a separate Linux Bridge on the PVE host.

The diagram below shows the conceptual network layout. All VMs connect to the private network interface vmbr1. VMs that need to be accessible from the home network also connect to the vmbr0 interface.
To provide internet access to private VMs, NAT is implemented from vmbr1 through vmbr0.

You can add the private network interface through the Proxmox admin or using default Debian tooling.

Let’s go with the second option and add the following configuration to the /etc/network/interfaces file:

auto vmbr1
iface vmbr1 inet static
    address 10.0.2.1/24
    bridge-ports none
    bridge-stp off
    bridge-fd 0

Activate the new interface with this command:

ifup vmbr1

The newly created interface should appear in the Proxmox control panel.

To give VMs internet access, you need to set up NAT.

In the /etc/sysctl.conf file, enable IP forwarding by adding this line:

net.ipv4.ip_forward=1

Apply this setting right away with the following command:

sysctl -w net.ipv4.ip_forward=1

Next, enable NAT in iptables with this command:

iptables -t nat -A POSTROUTING -s 10.0.2.0/24 -o vmbr0 -j MASQUERADE

Here, vmbr0 is the name of the interface with internet access.

To preserve iptables settings across reboots, install the iptables-persistent package:

apt install iptables-persistent

The network is now configured, and we can move on to the next step.

Preparing the Image

To create VMs similar to those in the cloud, you need a special Debian cloud image.

You’ll also need tools to modify virtual machine images:

apt install libguestfs-tools

Here’s the command to download and prepare the image for use as a template:

wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2 \
&& virt-customize -a debian-12-generic-amd64.qcow2 --install qemu-guest-agent,net-tools \
&& virt-customize -a debian-12-generic-amd64.qcow2 --run-command "echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen" \
&& virt-customize -a debian-12-generic-amd64.qcow2 --run-command "locale-gen" \
&& virt-customize -a debian-12-generic-amd64.qcow2 --run-command "update-locale LANGUAGE=en_US.UTF-8 LC_ALL=en_US.UTF-8 LC_CTYPE=en_US.UTF-8 LANG=en_US.UTF-8" \
&& virt-customize -a debian-12-generic-amd64.qcow2 --truncate /etc/machine-id

In the --install argument, you can specify additional packages that will be automatically installed every time. The qemu-guest-agent package is required for the PVE agent to work.

It’s also important to run --truncate /etc/machine-id so that a unique identifier is generated for each copied VM.

Locale manipulations aren’t mandatory, but they help avoid pesky locale error messages when working via SSH.

Once the image is prepared, you need to create the actual VM template in Proxmox. You can do this with the following command:

QM_ID=9001 \
&& qm create $QM_ID --name "debian12-cloudinit" --memory 512 --cores 1 --net0 virtio,bridge=vmbr1 --machine q35 \
&& qm importdisk $QM_ID debian-12-generic-amd64.qcow2 local-lvm \
&& qm set $QM_ID --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-$QM_ID-disk-0 \
&& qm set $QM_ID --boot c --bootdisk scsi0 \
&& qm set $QM_ID --ide2 local-lvm:cloudinit \
&& qm set $QM_ID --serial0 socket --vga serial0 \
&& qm set $QM_ID --agent enabled=1 \
&& qm template $QM_ID

The template ID (9001) and name ("debian12-cloudinit") can be changed to any arbitrary values. Resources and network settings will be redefined for each copied instance.

All preparations are done, and now you can use Terraform to manage virtual servers.

Terraform

To work with Proxmox via Terraform or OpenTofu, you can use the telmate/proxmox provider.

For security reasons, it’s recommended to create a separate user with limited permissions. However, in a home environment with access only from the local network, you can skip this step.

Contents of the provider.tf file:

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "3.0.2-rc03" # latest version at the time of writing: 3.0.2-rc07
    }
  }
}

provider "proxmox" {
  pm_api_url      = "https://${var.pm_host}:8006/api2/json"
  pm_user         = "${var.pm_user}@pam"
  pm_password     = var.pm_password
  pm_tls_insecure = true
}

Contents of the variables.tf file:

variable "pm_user" {}
variable "pm_password" { sensitive = true }
variable "pm_host" {}
variable "ssh_key" { default = "~/.ssh/id_rsa.pub" }

After installing the provider with the terraform init command, you can describe the infrastructure just like when working with cloud providers.

You can refer to the previously created cloud template either by name using clone or by its ID using clone_id.

Example of creating a virtual server accessible only on the private network:

locals {
  debian_template    = "debian12-cloudinit"
  debian_template_id = 9001
}

resource "proxmox_vm_qemu" "internal-vm" {
  vmid        = 310
  name        = "internal-vm"
  target_node = "pve-1"
  clone       = local.debian_template
  onboot      = true
  cpu {
    cores = 1
  }
  memory           = 512
  boot             = "order=scsi0"
  scsihw           = "virtio-scsi-single"
  agent            = 1
  vm_state         = "running"
  automatic_reboot = true

  ciupgrade = false
  ipconfig0 = "ip=10.0.2.11/24,gw=10.0.2.1"
  skip_ipv6 = true
  ciuser    = "cloud"
  sshkeys   = file(var.ssh_key)

  serial {
    id = 0
  }

  disks {
    scsi {
      scsi0 {
        disk {
          storage = "local-lvm"
          size    = "8G"
        }
      }
    }
    ide {
      ide1 {
        cloudinit {
          storage = "local-lvm"
        }
      }
    }
  }

  network {
    id     = 0
    bridge = "vmbr1"
    model  = "virtio"
  }
}

To create a server accessible on the local network, specify an additional bridge and its configuration:

# ...

resource "proxmox_vm_qemu" "jump-host" {
  vmid        = 110
  name        = "jump-host"
  target_node = "pve-1"
  clone_id     = local.debian_template_id
  # ...
  ipconfig0 = "ip=10.0.2.10/24,gw=10.0.2.1"
  ipconfig1 = "ip=dhcp"

  # ...

  network {
    id     = 0
    bridge = "vmbr1"
    model  = "virtio"
  }

  network {
    id      = 1
    bridge  = "vmbr0"
    model   = "virtio"
    macaddr = "AA:24:11:75:01:10"
  }
}

The VM’s MAC address is fixed to create static IPs on the DHCP server side. The VMs created above are accessible via SSH through the jump host using the cloud user and the SSH key specified in the
Terraform variables.

Working with a PVE Cluster

To manage cluster infrastructure, you can connect to any node’s API. In PVE, there’s no “master” host. By connecting to one node’s API, you can manage resources on other nodes.

However, if Terraform state includes resources on a powered-off node, TF will fail with an error. Therefore, when using Terraform, all cluster nodes with managed resources must be available.

Quorum Error

To simulate distributed systems for testing, I use a cluster of two hosts. Most of the time, I don’t need both PVE hosts, and only one is powered on.

By default, this approach leads to a “cluster not ready - no quorum?” error and makes Proxmox completely unusable.

To allow the cluster to work with just one node, run this command:

pvecm expect 1

To make this setting persistent, add three lines to the /etc/pve/corosync.conf file:

# ...

quorum {
  # ... defaults

  expected_votes: 1
  two_node: 0
  wait_for_all: 0
}

# ...

Working with Templates

Since the VM template image is stored on the local file system, you need to create it on each host.

Proxmox expects unique server and template IDs at the cluster level, so:

when preparing a template on each host, you must change its ID;
when using clone_id in Terraform, you must specify the template ID located on the specified target_node.

RU translation

Declarative rendering of react-query state via switch-query

Mikhail Panichev — Mon, 09 Feb 2026 00:42:00 +0000

Russian version

switch-query is a tiny npm package that simplifies displaying the state from @tanstack/react-query. It exports a single component, SwitchQuery, along with its types. Despite its simplicity, the package streamlines code structure and enables more thoughtful design UI/UX.

Request states

In general, to provide users with the most accurate information retrieved from the server, the following scenarios must be considered:

Success — the request was successful, and data is displayed.
Failure — the request resulted in an error.
Loading — the request is in progress, and data is not yet available.
Empty state — the response was successful, but there is no data.

@tanstack/react-query implements types narrowing. This allows you to explicitly separate request states using strict typing.

Let’s take an example from the official website:

import { useQuery } from '@tanstack/react-query';

function Todos() {
    const { data, isPending, error } = useQuery({
        queryKey: ['todos'],
        queryFn: () => fetch('/api/todos').then((r) => r.json()),
    });

    if (isPending) {
        return <span>Loading...</span>;
    }

    if (error) {
        return <span>Oops!</span>;
    }

    return (
        <ul>
            {data.map((t) => (
                <li key={t.id}>{t.title}</li>
            ))}
        </ul>
    );
}

export default Todos;

In my opinion, this is one of the library’s key advantages: it encourages developers to create more thoughtful user interfaces.

However, when using if and return statements, it becomes inconvenient to add elements common to each state. For example, let’s add a container and a create button.

Example of modified code

import { useQuery } from '@tanstack/react-query';

function Todos() {
    const { data, isPending, error } = useQuery({
        queryKey: ['todos'],
        queryFn: () => fetch('/api/todos').then((r) => r.json()),
    });

    if (isPending) {
        return (
            <div className="container">
                <span>Loading...</span>
                <button>add</button>
            </div>
        );
    }

    if (error) {
        return (
            <div className="container">
                <span>Oops!</span>
                <button>add</button>
            </div>
        );
    }

    return (
        <div className="container">
            <ul>
                {data.map((t) => (
                    <li key={t.id}>{t.title}</li>
                ))}
            </ul>
            <button>add</button>
        </div>
    );
}

export default Todos;

An alternative using conditions within JSX solves the code duplication issue but is less explicit and leaves room for errors, such as displaying multiple states simultaneously:

import { useQuery } from '@tanstack/react-query';

function Todos() {
    const { data, isPending, error, isSuccess } = useQuery({
        queryKey: ['todos'],
        queryFn: () => fetch('/api/todos').then((r) => r.json()),
    });

    return (
        <div className="container">
            {isPending && <span>Loading...</span>}

            {error && <span>Oops!</span>}

            {isSuccess && (
                <ul>
                    {data.map((t) => (
                        <li key={t.id}>{t.title}</li>
                    ))}
                </ul>
            )}
            <button>add</button>
        </div>
    );
}

export default Todos;

With switch-query, this task is easily solved by encapsulating checks within a nested JSX element:

import { useQuery } from '@tanstack/react-query';
import { SwitchQuery } from 'switch-query';

function Todos() {
    const query = useQuery({
        queryKey: ['todos'],
        queryFn: () => fetch('/api/todos').then((r) => r.json()),
    });

    return (
        <div className="container">
            <SwitchQuery
                query={query}
                pending={<span>Loading...</span>}
                error={<span>Oops!</span>}
                success={({ data }) => (
                    <ul>
                        {data.map((t) => (
                            <li key={t.id}>{t.title}</li>
                        ))}
                    </ul>
                )}
            />
            <button>add</button>
        </div>
    );
}

export default Todos;

This approach is more convenient in the JSX context. There’s no need to excessively decompose components or use nested ternary operators.

Multiple queries in a single component

Rendering via JSX allows working with multiple queries in a single component.

Suppose each item references a tag dictionary via tagId, and we need to display the tag title.

In this case, you can nest <SwitchQuery /> elements within each other. The order in which responses are received doesn’t matter, as all states are accounted for at every level.

import { useQuery } from '@tanstack/react-query';
import { SwitchQuery } from 'switch-query';

function Todos() {
    const todos = useQuery({
        queryKey: ['todos'],
        queryFn: () => fetch('/api/todos').then((r) => r.json()),
    });
    const tags = useQuery({
        queryKey: ['tags'],
        queryFn: () => fetch('/api/tags').then((r) => r.json()),
    });

    return (
        <div className="container">
            <SwitchQuery
                query={todos}
                pending={<span>Loading...</span>}
                error={<span>Oops!</span>}
                success={({ data }) => (
                    <ul>
                        {data.map((t) => (
                            <li key={t.id}>
                                {t.title}
                                <SwitchQuery
                                    query={tags}
                                    success={({ data }) => data.title}
                                    pending="loading..."
                                    error={`#${t.tagId}`}
                                />
                            </li>
                        ))}
                    </ul>
                )}
            />
            <button>add</button>

            <div>
                <h2>Tags:</h2>
                <SwitchQuery
                    query={tags}
                    success={({ data }) => (
                        <ul>
                            {Object.keys(data).map((id) => (
                                <li key={id}>{data.title}</li>
                            ))}
                        </ul>
                    )}
                    pending="loading..."
                    error={({ error, refetch }) => (
                        <>
                            <div>{error.message}</div>
                            <button onClick={() => refetch()}>retry</button>
                        </>
                    )}
                />
            </div>
        </div>
    );
}

export default Todos;

Implementing such a view without switch-query would require creating additional components.

Empty states

For good design, it’s also important to explicitly inform the user when there is no data.

In switch-query empty state case is moved to additional props:

<SwitchQuery
    query={query}
    success={({ data }) => (
        <ul>
            {data.map((t) => (
                <li key={t.id}>{t.title}</li>
            ))}
        </ul>
    )}
    checkIsEmpty={(data) => !data.length}
    empty={<div>Nothing to do</div>}
/>

Handling all possible states is brought to a more declarative style.

Conclusion

One might argue that all the examples above are flawed and it would be better to move everything into separate components. This is a perfectly valid stance and you could even use useSuspenseQuery.

However, in this case, implementation of a single interface block would be spread across multiple components and files, which would also need to be named.

I believe that @tanstack/react-query blurs established patterns by making the request an integral part of the views, which aligns with the final result. The library’s declarative API is perfectly complemented by the declarative nature of JSX.

Star on GitHub

Do you know the software to host a webinar?

Mikhail Panichev — Thu, 19 Mar 2020 12:12:39 +0000

Hi everyone!

Because of COVID-19 my client's trainers are restricted to go to business trips but have to land the same count of workshops annually.

So we decided to use a platform for webinars to do those workshops remotely but we can't find a solution.

We checked out YouTube Live and some SAAS solutions but they don't meet the client's requirements.

What we need:

Ability to integrate all functionality (video stream, chat room, etc.) to our website;
Ability to record webinars and host those videos on our website in the archive;
Ability to style UI of the player and chat (branding);
The solution can be paid or some OSS projects as well;
The client doesn't want to show any attribution (I, personally, think that it's okay and even great to show solution attribution).

Easy data animations in Vue with Vuenime

Mikhail Panichev — Mon, 16 Sep 2019 22:41:01 +0000

Few times in a row I have been creating data visualizations with animations that incapable of CSS transitions. Every time I implemented all animation logic from scratch using Animejs.
Except for the last one when I realized that the combination of the watch property and anime call can provide a simple way to create a wrapper component for declarative animations.

And I wrote it.

Then I discovered that there are no such packages in npm. Okay, there is vue-anime but it just adds $anime to Vue prototype and provides v-anime directive (which is limited to DOM node; also I don't use directives at all because of JSX).

And I made an npm package.

Frankly, it was a long process of finding free time, deciding how to provide documentation, which features are necessary for release, and so on. But I turned off the perfectionism and here it is!

I hope you find this package useful and give me some feedback!

NPM Package
GitHub Repo
Storybook

Vue-emit: an npm package to dispatch events in Vue.js

Mikhail Panichev — Sun, 21 Oct 2018 11:49:35 +0000

Source code | NPM

Vue.js provides an API for dispatching events in components by this.$emit. But in functional components, you don't have this instance at all and many people who didn't previously worked with functional components, ask "How to emit an event in a functional component?"

The first solution is to use props for event listeners. It such a React way. The problem that in this case, you have strictly defined event name, can't use @ / v-on / v-model syntax and have some additional difficulties in implementing transparent wrappers. Example:

// Child component
export default {
  name: 'base-input',
  functional: true,
  props: {
    onInput: {
      type: Function,
      default: () => (),
    },
  },
  render (h, context) {
    return (
      <input
        onInput={context.props.onInput}
        {...{
          attrs: context.data.attrs,
          on: context.listeners,
        }}
      />
    );
  },
};

<!-- Parent component template -->
<template>
  <base-input onInput="doSomething" />
</template>

The second solution is to use context.listeners. This is a good way to dispatch an event in Vue.js. Example:

// Child component
export default {
  name: 'base-input',
  functional: true,
  render (h, context) {
    return (
      <input
        onInput={e => context.listeners.input(e.target.value)}
        {...{
          attrs: context.data.attrs,
          on: context.listeners,
        }}
      />
    );
  },
};

<!-- Parent component template -->
<template>
  <base-input @input="doSomething" />
</template>

But there are some pitfalls when using context.listeners. I've found two situations when you will get TypeError: context.listeners.yourEvent is not a function

1. Listener can be `undefined` (not proveded)

If you don't pass a listener from the parent component, there is no handler for the event (input event in our case) in context.listeners object.

2. Listener value can be a function

The picture above shows the example structure of components and listeners. It this structure context.listeners.input in the C component will be an array of two functions: [doSomethingA, doSomethingB]. This is also true for this.$listeners.

So when using context.listeners (either directly calling handlers from this.$listeners) you have to always check that listener exists and what type it has: Function or Array.

Using vue-emit

To solve above problems I've wrote the helper function that do all checks and provides the API similar to $emit. Thats how to use it:

yarn add vue-emit

import emit from 'vue-emit';

export default {
  name: 'base-input',
  functional: true,
  render (h, context) {
    return (
      <input
        onInput={e => emit(context.listeners, 'input', e.target.value)}
      />
    );
  },
};

The first argument is an object of listeners with eventName => handler structure. It is a standard Vue this.$listeners and context.listeners objects.

The second argument is an event name. Vue-emit will check listeners object and do nothing if handler is not defined or will call each handler if there are more than one listener.

You can also pass any amount of additional parameters and they all will be passed to handler. By the way, this is the use case with stateful components - when for some reason, you want to pass more than one argument to handler function as a payload.

Conclusion

I hope you will find this package useful and enjoyed reading this article. Feel free to ask your questions, open issues, pull request etc.

denisinvader / vue-emit

Helper function for emitting events in Vue.js (functional) components

Vue emit

Helper function to emit events from Vue.js functional components. Can be used in regular components too CodeSandbox demo

Installation

yarn add vue-emit
# or
npm install vue-emit

Usage

import emit from 'vue-emit';

export default {
  functional: true,
  render (h, context) {
    return (
      <button
        onClick={e => emit(context.listeners, 'someEvent', e, 'additional param', 'etc')}
      >
        {context.children}
      </button>
    );
  },
};

Params

emit(handlers_list, event_name, [optional_payload]);

handlers_list - object of functions. In Vue this is this.$listeners and context.listeners (for funtional components). Each value may be a function or an array of functions. In case of array emit will call all provided callbacks.
event_name - name of the event to fire. The event may not be…

View on GitHub

Photo by Daniele Riggi on Unsplash

Mounted and BeforeDestroy Hooks in Vue.js functional components.

Mikhail Panichev — Sun, 21 Oct 2018 09:39:47 +0000

When you using Vue.js functional components you have nothing except render function and it's context with some parameters.

I always prefer to use functional component instead of a stateful component in my shared components library at work and it works fine when I don't need state. But sometimes I need mounted and beforeDestroy hooks in a stateless component.

The problem

Let's look at the example. We need a simple modal component that renders some overlay and block with passed children. Something like this:

export default {
  functional: true,
  render (h, context) {
    return (
      <div class="modal">
        <div class="modal__overlay" />
        <div class="modal__content">{context.children}</div>
      </div>
    );
  },
};

I didn't provide any styles but it should look like bootstrap modal. Now if the window has y scroll opened modal will be moving with page scroll. To create better UX we should disable scroll when modal is opened and enable it again when modal is closed. When using usual components you can do it in mounted and befoDestroy hooks:

export default {
  // ...
  mounted () {
    document.body.style.overflow = 'hidden';
  },
  beforeDestroy () {
    document.body.style.overflow = null;
  },
  // ...
};

But how to implement this logic without hooks? The answer is: using <transition> component with appear prop!

The solution

<transition> component has its own hooks for entering and leaving, so we can just wrap all our component in it and define hooks. The appear prop guarantees that our "mounted" hook will be fired when component mounts.

const mounted = () => {
  document.body.style.overflow = 'hidden';
};
const beforeDestroy = () => {
  document.body.style.overflow = null;
};

export default {
  functional: true,
  render (h, context) {
    return (
      <transition
        appear
        name="fade"
        onAfterEnter={mounted}
        onBeforeLeave={beforeDestroy}
      >
        <div class="modal">
          <div class="modal__overlay" />
          <div class="modal__content">{context.children}</div>
        </div>
      </transition>
    );
  },
};

That's it! Now we have some hooks in a functional component.

You can also improve your UI by implementing transition animations.

Photo by Suad Kamardeen on Unsplash

Creating an interactive map with D3 and Vue

Mikhail Panichev — Sun, 07 Oct 2018 00:13:52 +0000

Source code | Live preview

Why do I need it at all

There are many ways to include a map in your website or application: Google Maps, Mapbox, Leaflet etc. It's simple. Some services allows you to do it in just few clicks.

But it's getting bad when you need to customise the design, display some dataset or do whatever you want. Moreover, in Vue or React you can't use JSX and have to use imperative abstract javascript API (but I use Vue because I'm very excited by templates and reactivity).

Also some libraries are not free for private projects.

So once again I had to display some data on map I decided: I want full control in my code and I will create my own map with blackjack and hookers.

Step 1: Create a static map.

Let's start with simple vue-cli 3 app with Babel and sass.

We need D3 and d3-tile (it doesn't included in d3 npm package) for rendering map tiles.

yarn add d3 d3-tile

Actually we don't need whole d3 code. For a simple map we only need d3-geo for map projection and d3-tile for generating tiles, so we will include only these packages.

Next we should define some settings like scale, width, height and initial coordinates. Usually I make all my charts responsive to it container by calculating element's size on mount.

<script>
const d3 = {
  ...require('d3-geo'),
  ...require('d3-tile'),
};

export default {
  props: {
    center: {
      type: Array,
      default: () => [33.561041, -7.584838],
    },
    scale: {
      type: [Number, String],
      default: 1 << 20,
    },
  },
  data () {
    return {
      width: 0,
      height: 0,
    };
  },
  mounted () {
    const rect = this.$el.getBoundingClientRect();

    this.width = rect.width;
    this.height = rect.height;
  },
  render () {
    if (this.width <= 0 || this.height <= 0) {
      // the dummy for calculating element size
      return <div class="map" />;
    }

    return (
      <div class="map">our map will be here</div>
    );
  },
};
</script>

<style lang="scss" scoped>
.map {
  width: 100%;
  height: 100%;
}
</style>

Now define the projection and tiles generator.

export default {
  // ... 
  computed: {
    projection () {
      return d3.geoMercator()
        .scale(+this.scale / (2 * Math.PI))
        .translate([this.width / 2, this.height / 2])
        .center(this.center)
      ;
    },
    tiles () {
      return d3.tile()
        .size([this.width, this.height])
        .scale(+this.scale)
        .translate(this.projection([0, 0]))()
      ;
    },
  },
  // ...
};

I always define d3 helper functions as computed properties, so when some params are changing Vue recalculates them and updates our component.

Now we have everything needed for displaying the map and we just render generated tiles:

export default {
  render () {
    if (this.width <= 0 || this.height <= 0) {
      return <div class="map" />;
    }

    return (
      <div class="map">
        <svg viewBox={`0 0 ${this.width} ${this.height}`}>
          <g>
            {this.tiles.map(t => (
              <image
                key={`${t.x}_${t.y}_${t.z}`}
                class="map__tile"
                xlinkHref={`https://a.tile.openstreetmap.org/${t.z}/${t.x}/${t.y}.png `}
                x={(t.x + this.tiles.translate[0]) * this.tiles.scale}
                y={(t.y + this.tiles.translate[1]) * this.tiles.scale}
                width={this.tiles.scale}
                height={this.tiles.scale}
              />
            ))}
          </g>
        </svg>
      </div>
    );
  },
};

Here we go through tiles generated by d3-tile and request images from tile server.

You can find other servers here or you can even host your own tile server with custom styles.

Don't forget to add a copyright.

<div class="map__copyright">
  ©&nbsp;
  <a
    href="https://www.openstreetmap.org/copyright"
    target="_blank"
  >OpenStreetMap&nbsp;</a>
  contributors
</div>

.map {
  // ...
  position: relative;
  font-family: Arial, sans, sans-serif;

  &__copyright {
    position: absolute;
    bottom: 8px;
    right: 8px;
    padding: 2px 4px;
    background-color: rgba(#ffffff, .6);
    font-size: 14px;
  }
}

Now we have the static map of Casablanca. Not very exciting yet.

Step 2: Add map controls.

The most exciting thing for me is how Vue makes simpler the way to create an interactive map. We just update projection params and map updates. It was like easy peasy magic at first time!

We'll make zoom buttons and position control by dragging the map.

Let's start with dragging. We need to define projection translate props in component data and some mouse event listeners on svg element (or you can listen them on tiles group).

<script>
// ...

export default {
  // ...
  data () {
    return {
      // ...
      translateX: 0,
      translateY: 0,

      touchStarted: false,
      touchLastX: 0,
      touchLastY: 0,
    };
  },
  computed: {
    projection () {
      return d3.geoMercator()
        .scale(+this.scale / (2 * Math.PI))
        .translate([this.translateX, this.translateY])
        .center(this.center)
      ;
    },
    // ...
  },
  mounted () {
    // ...
    this.translateX = this.width / 2;
    this.translateY = this.height / 2;
  },
  methods: {
    onTouchStart (e) {
      this.touchStarted = true;

      this.touchLastX = e.clientX;
      this.touchLastY = e.clientY;
    },
    onTouchEnd () {
      this.touchStarted = false;
    },
    onTouchMove (e) {
      if (this.touchStarted) {
        this.translateX = this.translateX + e.clientX - this.touchLastX;
        this.translateY = this.translateY + e.clientY - this.touchLastY;

        this.touchLastX = e.clientX;
        this.touchLastY = e.clientY;
      }
    },
  },
  render () {
    // ...
    return (
      <div class="map">
        <svg
          viewBox={`0 0 ${this.width} ${this.height}`}
          onMousedown={this.onTouchStart}
          onMousemove={this.onTouchMove}
          onMouseup={this.onTouchEnd}
          onMouseleave={this.onTouchEnd}
        >
          // ...
        </svg>
        // ...
      </div>
    );
  },
};
</script>

<style lang="scss" scoped>
.map {
  // ...

  &__tile {
    // reset pointer events on images to prevent image dragging in Firefox
    pointer-events: none;
  }
  // ...
}
</style>

Wow! We just update translate values and new tiles are loading so we can explore the world. But it isn't very comfortable to do without a zoom control, so let's implement it.

We need to move scale prop in component's data, add zoom property and render zoom buttons.

In my experience minimal and maximum tile's zoom level are 10 and 27 (honestly I'm not very sure that this correct for all tile providers).

<script>
// ...

const MIN_ZOOM = 10;
const MAX_ZOOM = 27;

export default {
  props: {
    center: {
      type: Array,
      default: () => [-7.584838, 33.561041],
    },
    initialZoom: {
      type: [Number, String],
      default: 20,
    },
  },
  data () {
    return {
      // ...
      zoom: +this.initialZoom,
      scale: 1 << +this.initialZoom,
    };
  },
  // ...
  watch: {
    zoom (zoom, prevZoom) {
      const k = zoom - prevZoom > 0 ? 2 : .5;

      this.scale = 1 << zoom;
      this.translateY = this.height / 2 - k * (this.height / 2 - this.translateY);
      this.translateX = this.width / 2 - k * (this.width / 2 - this.translateX);
    },
  },
  // ...
  methods: {
    // ...
    zoomIn () {
      this.zoom = Math.min(this.zoom + 1, MAX_ZOOM);
    },
    zoomOut () {
      this.zoom = Math.max(this.zoom - 1, MIN_ZOOM);
    },
  },
  render () {
    // ...
    return (
      <div class="map">
        <div class="map__controls">
          <button
            class="map__button"
            disabled={this.zoom >= MAX_ZOOM}
            onClick={this.zoomIn}
          >+</button>
          <button
            class="map__button"
            disabled={this.zoom <= MIN_ZOOM}
            onClick={this.zoomOut}
          >-</button>
        </div>
        //...
      </div>
    );
  },
};
</script>

<style lang="scss" scoped>
.map {
  // ...
  &__controls {
    position: absolute;
    left: 16px;
    top: 16px;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
    height: 56px;
  }
  &__button {
    border: 0;
    padding: 0;
    width: 24px;
    height: 24px;
    line-height: 24px;
    border-radius: 50%;
    font-size: 18px;
    background-color: #ffffff;
    color: #343434;
    box-shadow: 0 1px 4px rgba(0, 0, 0, .4);

    &:hover,
    &:focus {
      background-color: #eeeeee;
    }

    &:disabled {
      background-color: rgba(#eeeeee, .4);
    }
  }
  // ...
}
</style>

Here it is. In just two steps we created simple interactive map with Vue, D3 and OpenStreetMap.

Conclusion

It isn't hard to create your own map view component with the power of D3 and Vue's reactivity. I think that one of the most important things is the full control of DOM instead of using some abstract map renderer's API which will do some obscure things with my lovely elements.

Of course to make a good powerful map we need to implement more features like smooth zoom, max bounds etc. But all the stuff is fully customisable so you can do everything you want or need to do.

If you'll find this article useful I can write more about how to improve this map and display a data on it.

Please feel free to ask your questions.

DEV Community: Mikhail Panichev

Git Playbook: Team-sync and Stable Releases

Abstract

Prerequisites

Issue tracker

Testing process

The release process

The target change history

Git configuration

A Git hook for commit messages

Git working rules

How to Build a Home Cloud with Proxmox

Preparing a Private Network

Preparing the Image

Terraform

Working with a PVE Cluster

Quorum Error

Working with Templates

Declarative rendering of react-query state via switch-query

Request states

Multiple queries in a single component

Empty states

Conclusion

Do you know the software to host a webinar?

Easy data animations in Vue with Vuenime

Vue-emit: an npm package to dispatch events in Vue.js

1. Listener can be undefined (not proveded)

2. Listener value can be a function

Using vue-emit

Conclusion

denisinvader / vue-emit

Helper function for emitting events in Vue.js (functional) components

Vue emit

Installation

Usage

Params

Mounted and BeforeDestroy Hooks in Vue.js functional components.

The problem

The solution

Creating an interactive map with D3 and Vue

Why do I need it at all

Step 1: Create a static map.

Step 2: Add map controls.

Conclusion

1. Listener can be `undefined` (not proveded)