DEV Community: Mikhail Panichev

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

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)