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
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
If the installation is successful, you can check the version using:
charites -v
You can also check how to use the charites command by running:
charites -h
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.
{
"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.
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.
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
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
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
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:
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:
paint:
line-color: blue
line-width: 2
⬇️
paint:
line-color: blue
line-width: 10
After making these changes, the map now looks like this:
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:
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.
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
{
"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








