@jackdbd/eleventy-plugin-telegram

Eleventy plugin that sends Telegram messages when Eleventy starts/finishes building your site.

Installation
Usage
Configuration
Docs
Troubleshooting
Dependencies
License

Installation

npm install @jackdbd/eleventy-plugin-telegram

Note: this library was tested on Node.js >=18. It might work on other Node.js versions though.

Usage

In your Eleventy config file:

import { telegramPlugin } from '@jackdbd/eleventy-plugin-telegram'

export default function (eleventyConfig) {
  // some eleventy configuration...

  eleventyConfig.addPlugin(telegramPlugin, {
    chatId: 'YOUR_TELEGRAM_CHAT_ID', // or set process.env.TELEGRAM_CHAT_ID and leave this undefined
    token: 'YOUR_TELEGRAM_BOT_TOKEN', // or set process.env.TELEGRAM_BOT_TOKEN and leave this undefined
    textBeforeBuild: '⏱️ 11ty <b>started</b> building my website',
    textAfterBuild: '🏁 11ty <b>finished</b> building my website'
  })

  // some more eleventy configuration...
}

See Telegram sendMessage API method for formatting options.

Configuration

Key	Default	Description
`chatId`	`process.env.TELEGRAM_CHAT_ID`	Your Telegram chat ID
`token`	`process.env.TELEGRAM_BOT_TOKEN`	Your Telegram Bot token
`textBeforeBuild`	`undefined`	Text message to send when Eleventy starts building the site
`textAfterBuild`	`undefined`	Text message to send when Eleventy finishes building the site

If you forgot the API token of a Telegram bot you created, you can retrieve it at any time using BotFather. Just go to BotFather > bot list > API token.

⚠️ A few things to keep in mind

Telegram messages can be 1-4096 characters long, after entities parsing. See formatting options here.

Depending on the environment your building your 11ty website in, this plugin might not be able to send you the text message defined in textAfterBuild. For example, when building on Cloudflare Pages, I always receive the textBeforeBuild text, but not always the textAfterBuild text. My guess is that Cloudflare kills the Node.js process before all event handlers registered with eleventy.after are resolved.

Docs

Docs generated by TypeDoc

📖 API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Troubleshooting

This plugin uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=11ty-plugin:*

Dependencies

Package	Version
zod	`^3.23.0`
zod-validation-error	`^3.1.0`

⚠️ Peer Dependencies

This package defines 2 peer dependencies.

Peer	Version range
`@11ty/eleventy`	`>=2.0.0 or 3.0.0-alpha.6`
`debug`	`>=4.0.0`