netlify-plugin-discord-notifier

A Netlify build plugin to notify build statuses with Discord Webhook.

Installation

Use npm, yarn or pnpm to add the plugin to the devPendencies in package.json.

npm install -D netlify-plugin-discord-notifier

Add the plugin to your netlify.toml configuration file:

# netlify.toml

[[plugins]]
package = "netlify-plugin-discord-notifier"

Webhook

In order to send notifications to the right place, you first need to create a Discord Webhook to the channel in which you want to receive the build notifications, by following Discord documentation.

Once you have your webhook url, go to Netlify admin panel and add it as an environment variable as DISCORD_WEBHOOK_URL.

That's all you need to make this plugin work!

Plugin configuration

This plugin can either be configured via the netlify.toml file or via a discord-notifier.config.js or discord-notifier.config.ts file (see here)

Important

Note that discord-notifier.config.js and discord-notifier.config.ts will take precedence over any configuration done in netlify.toml

Bot

Add global bot configuration in your netlify.toml like so:

# netlify.toml

[[plugins]]
package = "netlify-plugin-discord-notifier"

    [plugins.inputs.bot]
    username = "My Bot"

Available attributes

Key	Type	Default
username	String	Netlify
avatarUrl	String	https://www.netlify.com/v3/static/favicon/icon-512.png

Event bound configuration

Each build event has its own configuration key. To change its configuration, update your netlify.toml:

# netlify.toml

[[plugins]]
package = "netlify-plugin-discord-notifier"

    [plugins.inputs.preBuild]
    disabled = false

Supported event keys

type SupportedEventKeys = 
  | "success" 
  | "error" 
  | "preBuild" 
  | "build" 
  | "postBuild" 
  | "end" 
  | "preDev" 
  | "dev";

Available attributes

Key	Type	Comment
disabled	Boolean
title	Template	See here on how to customise the title
description	Template	See here on how to customise the description
color	Hex color	Use Discord.js doc for color reference
showBuildId	Boolean
showContext	Boolean
showBranch	Boolean
showCommit	Boolean
showDiff	Boolean
showLogs	Boolean
customWebhookKey	String	Use it for custom env variable key (e.g. defining different webhook per event type)
templates	Templates	See here on how to customise templates
formatter	Formatter	See here for custom formatter

A default configuration is provided for each event (e.g. disabling notification for preDev and dev events) and available in config.ts.

Custom messages

If the default messages do not fulfill your need, you can customise them using the templates, title and description attributes.

Templating is handle by eta and allows you to inject variables in your messages.

The templates object is as follows:

Key	Default
buildId	<%= it.env["BUILD_ID"] %>
context	<%= it.env["CONTEXT"] %>
branch	<%= it.env["BRANCH"] %>
commit	[<%= it.env["COMMIT_REF"] %>](<%= it.meta.commitUrl %>)
diff	<%= it.meta.diffUrl %>
logs	<%= it.meta.logsUrl %>

and supports the following values:

type TemplateParameters = {
  // https://docs.netlify.com/extend/develop-and-share/develop-build-plugins/#environment-variables
  env: Record<string, unknown>;
  // https://docs.netlify.com/extend/develop-and-share/develop-build-plugins/#inputs
  inputs: Record<string, unknown>;
  // https://docs.netlify.com/extend/develop-and-share/develop-build-plugins/#constants
  constants: Record<string, unknown>;
  // https://docs.netlify.com/extend/develop-and-share/develop-build-plugins/#netlifyconfig
  netlifyConfig: Record<string, unknown>;
  // https://docs.netlify.com/extend/develop-and-share/develop-build-plugins/#packagejson
  packageJson: Record<string, unknown>;
  
  // The complete configuration object produced after inputs
  config: Config;
  // The event bound configuration
  statusConfig: EventConfig;
  
  // Metadata
  meta: {
    // Application url to Netlify (https://app.netlify.com/sites/XXX)
    appUrl: string;
    // Current server time as string
    time: string;
    // URL of the commit associated with the build
    commitUrl: string;
    // URL for the deployed artifact (production or preview)
    deployUrl: string;
    // URL for the git diff between current and previous build
    diffUrl: string;
    // URL for the build logs
    logsUrl: string;
  };
}

Custom setup example

# netlify.toml

[[plugins]]
package = "netlify-plugin-discord-notifier"

    [plugins.inputs.postBuild]
    disabled = false
    title = 'Build passed flawlessly! 💯'
    description = '[<%= it.env["SITE_NAME"] %>](<%= it.meta.deployUrl  %>) has finished building at <%= it.meta.time %>. Ship it! 🚢'
    
    [plugins.inputs.preBuild]
    disabled = false
    title = 'A new build has been launched! 🚀'
    description = '[<%= it.env["SITE_NAME"] %>](<%= it.meta.deployUrl  %>) has started a new build at <%= it.meta.time %>. Let´s rock! 🤘🎸'
    showBranch = true

    [plugins.inputs.preBuild.templates]
    branch = '<%= it.env["BRANCH"] %> - <% if (it.env["PULL_REQUEST"] !== "false") { %> PR <% } else { %> Not a PR <% } %>'

Javascript / Typescript config file

The same configuration can be defined within a discord-notifier.config.js or discord-notifier.config.ts file.

// discord-notifier.config.ts
import type {DiscordNotifierConfig} from 'netlify-plugin-discord-notifier';

const config: DiscordNotifierConfig = {
  postBuild: {
    disabled: false,
    title: 'Build passed flawlessly! 💯',
    description: '[<%= it.env["SITE_NAME"] %>](<%= it.meta.deployUrl  %>) has finished building at <%= it.meta.time %>. Ship it! 🚢'
  },
  preBuild: {
    disabled: false,
    title: 'A new build has been launched! 🚀',
    description: '[<%= it.env["SITE_NAME"] %>](<%= it.meta.deployUrl  %>) has started a new build at <%= it.meta.time %>. Let´s rock! 🤘🎸',
    showBranch: true,
    templates: {
      branch: '<%= it.env["BRANCH"] %> - <% if (it.env["PULL_REQUEST"] !== "false") { %> PR <% } else { %> Not a PR <% } %>',
    }
  }
}

// Default export should contain the config object
export default config;

Fully custom webhook

If that's not enough, you can simply use a formatter function on each event configuration and return the object you want to send.

// discord-notifier.config.ts
import type {
  DiscordNotifierConfig,
  BuildEventParams,
  DiscordBody
} from 'netlify-plugin-discord-notifier';

const config: DiscordNotifierConfig = {
  // ...
  preBuild: {
    disabled: false,
    // ...
    // Formatter overrides all other parameters
    formatter: (params: BuildEventParams): DiscordBody => {
      return {
        username: 'My bot',
        embeds: [{
          title: 'Build is starting',
          description: `I just need to know **${process.env["SITE_NAME"]}** started building`,
        }],
      }
    }
  }
}

export default config;