electron-publish Module

Publishing infrastructure for electron-builder

The electron-publish module provides the publishing infrastructure used by electron-builder to upload artifacts to various hosting providers.

Installation

npm install electron-publish --save-dev

PublishOptions Interface

Options for controlling when to publish artifacts.

interface PublishOptions {
  publish?: PublishPolicy | null
}

publish · PublishPolicy | null

When to publish artifacts.

• "onTag" - Publish only if building a tagged commit
• "onTagOrDraft" - Publish on tag or if GitHub release is a draft
• "always" - Always publish
• "never" - Never publish

PublishContext Interface

Context provided to publishers.

interface PublishContext {
  readonly cancellationToken: CancellationToken
  readonly progress: MultiProgress | null
}

cancellationToken · CancellationToken

Token for cancelling upload operations.

progress · MultiProgress | null

Progress bar manager for displaying upload progress.

UploadTask Interface

Represents a file to be uploaded.

interface UploadTask {
  file: string
  fileContent?: Buffer | null
  arch: Arch | null
  safeArtifactName?: string | null
  timeout?: number | null
}

file · string · required

Path to the file to upload.

fileContent · Buffer | null

Optional file content buffer (instead of reading from file path).

arch · Arch | null

Architecture of the artifact (or null if not architecture-specific).

safeArtifactName · string | null

Safe artifact name for display/logging.

timeout · number | null

Upload timeout in milliseconds.

Publisher Classes

Base class and platform-specific publishers for uploading artifacts.

Publisher (Abstract)

Abstract base class for all publishers.

abstract class Publisher {
  protected constructor(context: PublishContext)
  
  abstract get providerName(): PublishProvider
  abstract upload(task: UploadTask): Promise<any>
  abstract toString(): string
}

Source: packages/electron-publish/src/publisher.ts:13

GitHubPublisher

Publishes to GitHub Releases.

const { GitHubPublisher } = require("electron-publish")

Configuration:

{
  "provider": "github",
  "owner": "my-org",
  "repo": "my-repo",
  "token": "ghp_xxxxx"
}

S3Publisher

Publishes to Amazon S3.

const { S3Publisher } = require("electron-publish")

Configuration:

{
  "provider": "s3",
  "bucket": "my-bucket",
  "region": "us-east-1"
}

SpacesPublisher

Publishes to DigitalOcean Spaces.

const { SpacesPublisher } = require("electron-publish")

Configuration:

{
  "provider": "spaces",
  "name": "my-space",
  "region": "nyc3"
}

GitlabPublisher

Publishes to GitLab Releases.

const { GitlabPublisher } = require("electron-publish")

Configuration:

{
  "provider": "gitlab",
  "owner": "my-group",
  "repo": "my-project"
}

BitbucketPublisher

Publishes to Bitbucket Downloads.

const { BitbucketPublisher } = require("electron-publish")

Configuration:

{
  "provider": "bitbucket",
  "owner": "my-workspace",
  "slug": "my-repo"
}

KeygenPublisher

Publishes to Keygen.

const { KeygenPublisher } = require("electron-publish")

Configuration:

{
  "provider": "keygen",
  "account": "my-account",
  "product": "my-product"
}

SnapStorePublisher

Publishes to Snap Store.

const { SnapStorePublisher } = require("electron-publish")

Configuration:

{
  "provider": "snapStore",
  "channels": ["stable"]
}

HttpPublisher

Publishes to a generic HTTP endpoint.

const { HttpPublisher } = require("electron-publish")

Configuration:

{
  "provider": "generic",
  "url": "https://my-server.com/releases"
}

Utility Functions

getCiTag()

Gets the Git tag from CI environment variables.

function getCiTag(): string | null

Returns: Tag name from CI environment, or null if not in a tagged build.

Supported CI systems:

• Travis CI (TRAVIS_TAG)
• AppVeyor (APPVEYOR_REPO_TAG_NAME)
• CircleCI (CIRCLE_TAG)
• GitLab CI (CI_COMMIT_TAG)
• GitHub Actions (GITHUB_REF_NAME when GITHUB_REF_TYPE is “tag”)
• Bitrise (BITRISE_GIT_TAG)
• Bitbucket (BITBUCKET_TAG)

Example:

const { getCiTag } = require("electron-publish")

const tag = getCiTag()
if (tag) {
  console.log(`Building tagged release: ${tag}`)
}

Example: Custom Publisher

import { Publisher, PublishContext, UploadTask } from "electron-publish"
import { PublishProvider } from "builder-util-runtime"

class CustomPublisher extends Publisher {
  constructor(context: PublishContext, private config: any) {
    super(context)
  }
  
  get providerName(): PublishProvider {
    return "custom" as PublishProvider
  }
  
  async upload(task: UploadTask): Promise<void> {
    const progressBar = this.createProgressBar(
      task.safeArtifactName || task.file,
      (await stat(task.file)).size
    )
    
    // Upload logic here
    console.log(`Uploading ${task.file}...`)
    
    // Update progress
    if (progressBar) {
      progressBar.tick(100)
    }
  }
  
  toString(): string {
    return "Custom Publisher"
  }
}

Configuration in electron-builder

Publish configuration is specified in your build configuration:

{
  "build": {
    "appId": "com.example.app",
    "publish": [
      {
        "provider": "github",
        "owner": "my-org",
        "repo": "my-repo"
      },
      {
        "provider": "s3",
        "bucket": "my-bucket",
        "region": "us-east-1"
      }
    ]
  }
}

Or from command line:

electron-builder --publish always
electron-builder --publish onTag

Environment Variables

Publishers use environment variables for authentication:

• GitHub: GH_TOKEN or GITHUB_TOKEN
• GitLab: GITLAB_TOKEN
• Bitbucket: BITBUCKET_TOKEN
• S3: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• Spaces: DO_TOKEN
• Keygen: KEYGEN_TOKEN
• Snap Store: SNAPCRAFT_STORE_CREDENTIALS

Import Examples

CommonJS

const { GitHubPublisher, getCiTag } = require("electron-publish")

ES Modules / TypeScript

import { GitHubPublisher, getCiTag, PublishOptions } from "electron-publish"
import type { UploadTask, PublishContext } from "electron-publish"

See Also

• Publishing Documentation
• Auto Update Documentation
• electron-updater Module