Use your Netlify domain as a Mastodon username alias

You can make you@yourdomain.com point to a Mastodon account hosted on another instance. The profile still lives on that instance; the custom address acts as an alias that other servers can discover through WebFinger.

One option is the netlify-plugin-mastodon-alias package. This article reflects the package and Netlify configuration available when it was written in 2022, so verify that the dependency is still maintained before adding it to a current site.

First, install the package:

npm install netlify-plugin-mastodon-alias

Then configure it in netlify.toml:

[[plugins]]
package = "netlify-plugin-mastodon-alias"

[plugins.inputs]
    username = "${MASTODON_USER}"
    instance = "${MASTODON_DOMAIN}"
    # delete or comment the next line if you want "*@${ALIAS_DOMAIN}" to work rather than just "${ALIAS_USER}@${ALIAS_DOMAIN}"
    strictUsername = "${ALIAS_USER}"

Set the referenced environment variables in Netlify and deploy the site. With strictUsername enabled, only the configured alias is accepted. If you remove that line, any username on the alias domain can resolve to the same Mastodon account.

The smaller option: a rewrite

If you do not want another build plugin, add a Netlify rewrite instead:

[[redirects]]
  from = "/.well-known/webfinger"
  to = "https://INSTANCE_NAME/.well-known/webfinger?resource=acct:USER_HANDLE@INSTANCE_NAME"
  status = 200

Replace INSTANCE_NAME and USER_HANDLE with the account’s real values. The 200 status makes this a rewrite, so clients request the WebFinger endpoint on your domain while Netlify serves the response from the Mastodon instance.

For one fixed account, I prefer the rewrite because there is less code and no package to keep updated. Whichever method you choose, test the alias from a different Mastodon server after deploying it; federation is the part that matters.

← Back to all articles