Introduction

figmaid is a simple web server that serves locally installed fonts to Figma.

How does it work? (in a nutshell)

Figma allows local fonts through a background service they call FigmaAgent. It works by establishing a web server with two jobs: serving locally installed fonts and a single index file with metadata about these fonts.

It comes with some limitations though, most importantly the platform support, or lack thereof. FigmaAgent currently only supports Windows and macOS. figmaid runs on Linux natively and can run on Windows and macOS via Docker.

Here's what Figma does when you load a document:

1. Request index file from localhost (that's your computer!)
2. Add fonts from the JSON response to selection
3. If user uses one of these fonts get the file

figmaid is a workhorse. It eats fonts and spits out their metadata simply by walking through your directories (platform defaults, and any you specify in configuration), parses font tables and creates the index file.

In practice

1. Start the server and reload Figma, if open. Figma will now use fonts served by figmaid.
2. Individual font files are requested from the server.

Install

figmaid currently only supports Linux. Previous versions included precompiled binaries for macOS (arm64 and x64) as well as Windows. For the documentation of the last macOS/Windows version switch to tag v0.9.0. If you want to use custom directories and thus need figmaid on macOS/Windows, you can still use the Docker image and continue to get updates.

There's four ways you can install figmaid

1. With the installation script on Linux

   curl -fsSL https://raw.githubusercontent.com/jqpe/figmaid/main/install.sh | sh
   

2. Downloading a precompiled binary from releases

3. Using the Docker image, documented in figmaid in docker

4. Building from source

You can use figmaid on Windows/macOS via Docker, but you're probably better off using FigmaAgent unless you need custom directories. If you only intend on using installed fonts, FigmaAgent will pick those up.

To build from source install Rust. For a specific tag you can use the --tag argument, e.g. for Windows and macOS you're limited to <= v0.9.0.

cargo install --git https://github.com/jqpe/figmaid

Configuration

The default configuration looks like below:

{
  "$schema": "https://raw.githubusercontent.com/jqpe/figmaid/main/docs/schema.json",
  "port": 18412,
  "directories": [
    "/usr/share/fonts",
    "/usr/local/share/fonts",
    "~/.local/share/fonts"
  ]
}

The configuration file lives in $HOME/.config/figmaid/figmaid.json. Additionally you can use environment variables PORT and DIRS, they will have preference.

If you are using Ubuntu or Fedora no additional configuration is required if you only wish to use installed fonts. Other Linux distros may or may not have the same directories, see your font configuration file to be sure.

Custom directories figmaid doesn't care about where your font files are located or whether they're installed or not. To add a custom directory, specify it in directories. The path to the directory doesn't need to be absolute, if you have fonts in /Design/fonts/<sub_folder>/**/* you can just specify /Design/fonts.

Note about directories

1. The directory path doesn't have to be absolute, but shortcuts like the tilde ~ are not supported.
2. figmaid has to have access to the directory. This usually means that the user that started figmaid has to have access.
   1. On a related note: if you run as sudo, the home directory which figmaid uses to locate your configuration file will not be what you expect. If you for some reason want to run figmaid as sudo run the command with HOME=/home/<user> figmaid

Command-line interface

figmaid has a small CLI to perform common tasks. It ships as a single executable with a single subcommand to work with the configuration.

figmaid

Starts the server. It starts on the foreground by default.

figmaid config

Create, open and validate configuration

Run without subcommands to print current directories and amount of loaded fonts

USAGE:
    figmaid config <SUBCOMMAND>

OPTIONS:
    -h, --help    Print help information

SUBCOMMANDS:
    create      Create default configuration file
    help        Print this message or the help of the given subcommand(s)
    open        Open configuration file in text editor
    validate    Validate configuration

Usage

This section contains guides for different use cases like running figmaid in the background.

Running figmaid in the background

figmaid doesn't run in the background by default. You can configure this yourself if you need it.

Docker

Docker has a powerful feature called restart policies, which allows containers to start automatically if they exit or if Docker restarts, as such, running figmaid inside Docker is a great way of keeping figmaid alive. Read more in the dedicated Docker section: figmaid in Docker.

As systemd unit

If you are using Ubuntu, or a similar distro that uses systemd, you can create a unit file for figmaid in just a few minutes.

Prerequisites:

• You are a sudoer
• You know the executable path of figmaid (use which figmaid)
• You know your username
• Ideally you'd have a basic understanding of what systemd units do. Read more at the official systemd website.

While systemd supports user units, having them reload on reboot is not as straightforward. It would require enabling lingering with loginctl, with the major caveat that every single user service would be started on reboot.

Create the unit file

1. Below, replace <your username> with the user you installed figmaid to.
2. If you used the installation script, the executable path is /home/<your username>/.local/bin/figmaid .
3. Replace <figmaid executable> with the path to figmaid.

The code block is editable, and changes you made will be present if you click the copy button.

Change the User and ExecStart properties as described above.

[Unit]
Description=figmaid — font daemon for figma
Documentation=https://figmaid.pages.dev
Wants=network-online.target
After=network-online.target

[Service]
User=<your username>

ExecReload=/bin/kill -HUP $MAINPID
ExecStart=<figmaid executable>
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

Save the file to /etc/systemd/system/figmaid.service.

Then, to enable, start, and view the status of the service run the below commands:

sudo systemctl enable figmaid
sudo systemctl start figmaid
sudo systemctl status figmaid

View logs

sudo journalctl -eu figmaid

Here -e tells journalctl that we want it to automatically scroll to the end. -u tells that we're asking for an unit.

Update configuration

Currently figmaid doesn't reload the configuration when you reload the service. Instead, you must restart the service.

sudo systemctl restart figmaid

Note that for already configured directories, no restarting is necessary. Instead, you simply have to add the font to the configured directory and reload Figma.

figmaid in Docker

You can also run figmaid inside a container. This comes with obvious benefits such as Docker's restart policies, which let you delegate restarting figmaid to Docker so you don't have to. The minor caveat is that specifying additional directories is more of a chore and the container includes an operating system, adding roughly 50MB.

Nevertheless, the benefits overshadow the caveats here for most people. Let's see it!

docker run -d -p 18412:18412 \
-v /usr/share/fonts:/usr/share/fonts:ro \
-v ~/.config/figmaid/figmaid.json:/root/.config/figmaid/figmaid.json \
--name figmaid --restart always \
nykanen/figmaid

Step by step — what is the above telling Docker? First, the -d short flag starts the container in detached mode, meaning there's no shell output nor input. Secondly, you must bind the port 18412 to your local computer, this is done with the -p short flag. Otherwise figmaid will only be accessible from within the container which is not very useful.

The -v short flag stands for volume, and as you'd expect, it binds a directory from your computer to be accessible within the container. Again, this is a requirement in almost all cases, unless you intend to install fonts inside the container, which by any means you could do. Above, we expose two directories: the directory for installed fonts in Ubuntu / Fedora, and the configuration file. The short :ro option enforces that figmaid doesn't have access to write to those files — completely optional as figmaid only reads those files, but explicitness is great!

That's the gist of it, but take the time to understand the arguments. Before running the command blindly it is probably beneficial to lay out a plan so figmaid works for you in the future with minimal hassle. These docs will still be waiting for you if you need to change stuff later.

After succesfully configuring and starting figmaid, the output of docker container ls would be similar to below:

CONTAINER ID   IMAGE             COMMAND                  CREATED      STATUS       PORTS
c07e070bb470   nykanen/figmaid   "sh -c 'HOST=${HOST}…"   0 days ago   Up 0 hours   0.0.0.0:18412->18412/tcp, :::18412->18412/tcp

Take note of the PORTS value. 0.0.0.0:18412 is available from 18412/tcp on your local machine. To make sure that everything really went as expected, open http://localhost:18412/figma/font-files on a browser and you should get a big chunk of JSON.

Adding additional directories

Simply changing your configuration file is not enough, you must bind the directory from your host to the container. If you find you're adding a lot of directories, you can use figmaid's ability to walk directories. If you have fonts in $HOME/design/fonts and $HOME/Downloads specifying just $HOME might be the way to go. This is not free though — figmaid would walk all directories in $HOME — so pick a good middleground, unfortunately this is up to you to figure out.

To add new bind mounts to figmaid you must first delete the first iteration, e.g. docker rm -f figmaid then create a new container with the additional bind mount:

docker run -d -p 18412:18412 \
-v /usr/share/fonts:/usr/share/fonts:ro \
-v ~/Downloads:/root/Downloads:ro \
-v ~/.config/figmaid/figmaid.json:/root/.config/figmaid/figmaid.json:rw \
--name figmaid --restart always \
nykanen/figmaid

Above we bound the default directory for downloaded files on Ubuntu to /root/Downloads. Remember to add this directory to your configuration file by editing ~/.config/figmaid/figmaid.json and add the directory for what the directory path is inside the container. In this case our configuration file would contain the following directories: /usr/share/fonts and /root/Downloads.

Verify that directories are included

After adding directories it would be nice to know they actually are picked up by figmaid. Fortunately this is not that big of a checklist, and often you would do this only once, never having to think about it again.

To get a list of all mounts inside a container use

docker inspect figmaid --format "{{range .Mounts}}{{ .Source }} -> {{ .Destination }}
{{ end }}"

You should get an output similar to below:

/usr/share/fonts -> /usr/share/fonts
/home/$user/.config/figmaid/figmaid.json -> /root/.config/figmaid/figmaid.json

The left-hand side is the directory on your host machine. This would contain your configuration file and font directories. The right-hand side is what the path is inside the container. Therefore it's also the path you should have in your configuration file.

Let's verify this next. Open your configuration file on your host machine (whatever is on the left-hand side of -> /root/.config/figmaid/figmaid.json.) As introduced in configuration, the directories property lets you specify additional directories. In the above example we want to include the right-hand side of /usr/share/fonts, which just happens to be /usr/share/fonts, but it could be anything! After ensuring that you're using the correct directories, and checking that the configuration is valid (docker exec -it figmaid figmaid config validate), all there is left to do is refresh Figma, if open. You can also run docker exec -it figmaid figmaid config to list loaded directories.

Troubleshooting

When things don't go as expected this section contains instructions for common pitfalls.

My fonts are not showing up

Check that you have the server running: sudo netstat -l | grep 18412, or with ss: sudo ss -l | grep 18412

If it prints nothing, start the server with figmaid. At this point if figmaid panics with AddrInUse, see relevant docs.

If it prints something, but you are still not seeing your fonts:

1. Ensure you have the font installed or you have specified the directory where it lives in, see usage.
2. Reload Figma. Figma requests fonts when it's initialized and adding new fonts requires a refresh.
3. Run figmaid config validate to check that your configuration file is valid. If you accidentally mispelled something figmaid will fallback to the default configuration.
   • For a quick fix run DIRS=/your/directory figmaid
4. Run figmaid config open and check that you specified the correct directory.
5. Run figmaid config, this lists all directories and amount of loaded font files per directory. If you want to be extra spicy you can specify an absolute path to the direct parent of your font file with DIRS=/my/fontdir figmaid config. If figmaid picked up some fonts from this directory it would print your directory path followed by amount of fonts greater than zero.
6. If all else fails, the font might not have correct tables. I'd apprecatiate if you'd take the time to open a issue with the font file included.

figmaid figures out the font family by looking at it's metadata. In some cases the font family and filename don't match — in this case you should install the font and then open it in your platform's GUI and see what the font family actually is.

AddrInUse

This error happens when figmaid is trying to bind a port that is already in use by another program.

Solution

1. See what program is using the port

   • sudo netstat -ltnp | grep '18412'
   • If you don't have netstat you can replace it with ss, the output will be a little different.

2. Kill the program

     0.0.0.0:*             LISTEN      70793/figmaid
                                       ^pid  ^process name
   

   • With process name: pkill -e figmaid
   • With process ID: kill 70793

For services you can forcibly stop the service by running above commands as sudo, but stopping the service with sudo systemctl stop <process name> is recommended.