0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Using unvt/charites for Web Map Styling

0
Last updated at Posted at 2025-12-10

Introduction

Vector tiles themselves do not contain style information that defines how features are displayed on a web map, such as color or line width. Therefore, we need to prepare a separate style file.

In ArcGIS Online and MapLibre, we use a JSON file as a style file. However, a JSON file often contains thousands of lines because it includes styling information for all layers. As a result, it can be difficult to read and edit.

To address these issues, unvt/charites was developed. charites can convert a single JSON style file into multiple YAML files. In the YAML format, each layer has its own file. Since YAML is more human-readable, it is much easier to read and edit.

This article is written for map developers who would like to start using charites. While it is possible to create style files from scratch, it can be challenging for beginners. Therefore, in this article, we will use a prepared style file and modify it.

Goal

Set Up a charites Environment and Try Style Editing with charites

Testing Environment

macOS

  • macOS 15.6.1
  • Visual Studio Code 1.106.0
  • Node.js 22.14.0
  • npm 10.9.2
  • charites 2.1.9

Windows

  • Windows 11 Enterprise
  • Visual Studio Code 1.98.2
  • Node.js 22.14.0
  • npm 10.9.2
  • charites 2.1.9

Procedure

Step 1: Check your environment

Before we begin, we need to make sure that your development environment is properly set up.

Code Editor

If you do not have a code editor installed such as Visual Studio Code(VS Code), install one. I recommend VS Code, but you may use any editor you prefer.

Node.js and npm

Node.js: A runtime that allows you to run JavaScript outside the web browser.
npm: The package manager for Node.js.

Install Node.js yourself. Since npm is included when you install Node.js, there is no need to install npm separately.

Check the version of Node.js and npm

At the terminal or in PowerShell, run the following commands:

node -v
npm -v

Screenshot 2025-12-12 at 2.45.49 PM.jpg

You should use Node.js v20 or later.

If you use PowerShell, you may encounter the following error:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded 
because running scripts is disabled on this system. For more 
information, see about_Execution_Policies at 
https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ npm -v
+ ~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityEx 
   ception
    + FullyQualifiedErrorId : UnauthorizedAccess

In this case, run the following command to temporarily allow PowerShell to execute scripts:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Step 2: Install unvt/charites

Install unvt/charites by running the following command:

npm install -g @unvt/charites

Screenshot 2025-12-12 at 2.53.29 PM.jpg

If the installation is successful, you can check the version using:

charites -v

Screenshot 2025-12-12 at 2.54.59 PM.jpg

You can also check how to use the charites command by running:

charites -h

Screenshot 2025-12-12 at 2.56.48 PM.jpg

Now you are ready to use unvt/charites! 🎉

Step 3: Prepare the style file

As I mentioned in the introduction, we will use the prepared style file below and modify it.

original_style.json
{
  "version": 8,
  "name": "Sample Style",
  "sources": {
    "v": {
      "type": "vector",
      "tiles": [
        "https://k96mz.github.io/makeVectorTiles/Data/VTpractice/{z}/{x}/{y}.pbf"
      ],
      "minzoom": 0,
      "maxzoom": 4
    }
  },
  "sprite": "",
  "glyphs": "https://orangemug.github.io/font-glyphs/glyphs/{fontstack}/{range}.pbf",
  "layers": [
    {
      "id": "coastl",
      "type": "line",
      "source": "v",
      "source-layer": "coastl",
      "maxzoom": 5
    },
    {
      "id": "landmass",
      "type": "fill",
      "source": "v",
      "source-layer": "landmass",
      "maxzoom": 5,
      "paint": { "fill-color": "rgba(195, 176, 176, 1)" }
    },
    {
      "id": "riverl",
      "type": "line",
      "source": "v",
      "source-layer": "riverl",
      "maxzoom": 5,
      "paint": { "line-color": "blue", "line-width": 2 }
    }
  ]
}

Regarding the tiles, I have already prepared them.

Open your code editor, and create a working directory.
Then, create the file "original_style.json", and copy and paste the style contents into it.

Step 4: Convert the JSON file into YAML files

charites can convert a single JSON style file into multiple YAML files.

Make sure that the JSON file is located in your working directory.

Screenshot 2025-12-12 at 3.06.35 PM.jpg

You can convert the JSON file into YAML files using the following command:

charites convert original_style.json original_style.yml

After running the command, you will find the generated YAML files in your working directory.

Screenshot 2025-12-09 at 5.09.06 PM.jpg

original_style.yml
version: 8
name: Sample Style
sources:
  v:
    type: vector
    tiles:
      - https://k96mz.github.io/makeVectorTiles/Data/VTpractice/{z}/{x}/{y}.pbf
    minzoom: 0
    maxzoom: 4
sprite: ''
glyphs: https://orangemug.github.io/font-glyphs/glyphs/{fontstack}/{range}.pbf
layers:
  - !!inc/file layers/coastl.yml
  - !!inc/file layers/landmass.yml
  - !!inc/file layers/riverl.yml
coastl.yml
id: coastl
type: line
source: v
source-layer: coastl
maxzoom: 5
landmass.yml
id: landmass
type: fill
source: v
source-layer: landmass
maxzoom: 5
paint:
  fill-color: rgba(195, 176, 176, 1)
riverl.yml
id: riverl
type: line
source: v
source-layer: riverl
maxzoom: 5
paint:
  line-color: blue
  line-width: 2

Step 5: Start the charites live preview

charites includes a live preview feature.
When you update your YAML files, the changes are automatically reflected on the map.
Thanks to this feature, you can instantly see styling updates—such as layer colors or road widths—without manually refreshing the map each time. This greatly improves your workflow.

You can launch the live preview in your browser with the following command:

charites serve original_style.yml

Screenshot 2025-12-10 at 11.46.49 AM.jpg

Step 6: Modify feature styles

Now, let’s practice modifying some feature styles.
First, change the fill color of the landmass layer as shown below:

landmass.yml
paint:
  fill-color: rgba(195, 176, 176, 1)
⬇️
paint:
  fill-color: rgba(180, 185, 190, 1)

Next, change the line width of the riverl layer from 2 to 10:

riverl.yml
paint:
  line-color: blue
  line-width: 2
⬇️
paint:
  line-color: blue
  line-width: 10

After making these changes, the map now looks like this:

Screenshot 2025-12-10 at 12.19.16 PM.jpg

Step 7: Change the layer order

Let’s change the layer order to better understand how the style files are structured.

Here, I swapped the order of landmass.yml and riverl.yml:

original_style.yml
layers:
  - !!inc/file layers/coastl.yml
  - !!inc/file layers/landmass.yml
  - !!inc/file layers/riverl.yml
⬇️
layers:
  - !!inc/file layers/coastl.yml
  - !!inc/file layers/riverl.yml
  - !!inc/file layers/landmass.yml

As a result, the riverl layer is now hidden underneath the landmass layer.

Screenshot 2025-12-10 at 2.46.53 PM.jpg

This shows that the order of layers is important. Layers are rendered from the top of the file to the bottom.

After confirming the behavior, reset the layer order.

You can stop the preview process by pressing Ctrl + C in your terminal.

Step 8: Convert the YAML files back into a JSON file

Finally, let’s convert the YAML files back into a JSON file, since the style file needs to be provided in JSON format.
Use the following command to generate a new JSON file that includes all the changes we made:

charites build original_style.yml original_style2.json
original_style2.json
{
  "version": 8,
  "name": "Sample Style",
  "sources": {
    "v": {
      "type": "vector",
      "tiles": [
        "https://k96mz.github.io/makeVectorTiles/Data/VTpractice/{z}/{x}/{y}.pbf"
      ],
      "minzoom": 0,
      "maxzoom": 4
    }
  },
  "sprite": "",
  "glyphs": "https://orangemug.github.io/font-glyphs/glyphs/{fontstack}/{range}.pbf",
  "layers": [
    {
      "id": "coastl",
      "type": "line",
      "source": "v",
      "source-layer": "coastl",
      "maxzoom": 5
    },
    {
      "id": "landmass",
      "type": "fill",
      "source": "v",
      "source-layer": "landmass",
      "maxzoom": 5,
      "paint": {
        "fill-color": "rgba(180, 185, 190, 1)"
      }
    },
    {
      "id": "riverl",
      "type": "line",
      "source": "v",
      "source-layer": "riverl",
      "maxzoom": 5,
      "paint": {
        "line-color": "blue",
        "line-width": 10
      }
    }
  ]
}

Summary

This article provided a step-by-step introduction to using charites for web map styling.
We covered how to:

  • set up a charites environment
  • convert a JSON style file into YAML files
  • update styles using the live preview
  • adjust the layer order
  • convert the edited YAML files back into a JSON style file

By using charites, you can manage styles in a more readable format and improve your workflow when designing vector-tile-based web maps.

I hope this article helps you get started with web map styling using charites and encourages you to explore more advanced customization in your own projects.

Reference

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?