ntfy

Push notifications to your phone from Nuxt with ntfy: no account and no keys, priorities, tags and one notification that replaces itself instead of repeating.

ntfy is the shortest path from your server to a phone. Install the app, pick a topic name, and that is the whole setup. No account, no registration, no keys.

Copy this

Install ntfy on your phone, tap subscribe, and type a topic name. Anything, as long as it is hard to guess.

Configure it

.env

PIGEON_NTFY_TOPIC=my-deploys-8f2a1c

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-pigeon'],
  nuxtPigeon: {
    channels: {
      ntfy: true,
    },
  },
})

Send

server/api/hello.get.ts

export default defineEventHandler(async () => {
  await ntfy.send('Deploy failed on main', {
    title: 'nuxt-pigeon',
    priority: 5,
    tags: ['warning'],
  })

  return { ok: true }
})

Your phone rings, through do not disturb, with a warning triangle.

A public topic is a password. On ntfy.sh anyone who knows the name can read your notifications and publish to them. Use something nobody guesses, or run your own instance and put a token in PIGEON_NTFY_TOKEN.

One notification that updates itself

This is the best thing ntfy has, and it is one option. Publish again with the same sequence id and the notification on the phone is replaced rather than repeated:

for (const [index, step] of steps.entries()) {
  await ntfy.send(`Step ${index + 1} of ${steps.length}: ${step}`, {
    sequenceId: 'deploy-status',
    title: 'Deploy',
  })
}

One entry that counts up, instead of seven piling up in the shade. Leave sequenceId out and ntfy assigns one, which works just as well as a handle for edit and delete.

Every option

Option	What it does
`title`	The bold line above the message
`priority`	1 silent to 5, which rings through do not disturb
`tags`	Emoji and labels, `['warning', 'skull']`
`click`	Opened when the notification is tapped
`sequenceId`	Your own id, so a later message replaces this one
`media`	An image. A url is fetched by ntfy itself
`attach`	A url to attach without downloading it
`icon`	A small icon next to the text
`actions`	Buttons: open a url, send an HTTP request, broadcast
`email`	Also send it as an email
`call`	Also call a phone number
`delay`	Deliver later, `30min` or `tomorrow, 9am`
`markdown`	Render the body as Markdown
`topic`	Another topic than the configured one
`cache`, `firebase`	Turn off caching or push delivery

What will cost you an hour

It counts bytes, not characters. 4096 of them, and an umlaut costs two, an emoji four.
Editing needs server 2.16.0 or newer. An older self hosted instance does not know the field and publishes a second notification instead of replacing the first. No error, just a duplicate.
Titles travel as JSON, not as headers. ntfy also accepts X-Title, but HTTP headers are ASCII, so an umlaut in a title would have to be encoded. The module sends the body as JSON for that reason.
Bytes take a different route entirely. With a file the body is the file, so every option moves into headers. That happens for you, but it is why filename matters there.
There is no receiving. ntfy could be subscribed to over SSE, but that is a process that stays alive and nobody has asked for it yet.

Publishing - every option, with curl examples
Updating and deleting
Self hosting

Slack

Send Slack messages from Nuxt with an incoming webhook or a bot token: threads, file uploads, editing, deleting, and receiving through the Events API.

Mastodon

Post to Mastodon from Nuxt with an access token: visibility, content warnings, images, editing and deleting, plus polled notifications for your own account.