electron-forge-ipfs-publisher

IPFS Electron Publisher

How to publish your distributable Electron app artifacts to IPFS with web3.storage

The IPFS target publishes your Make artifacts to an IPFS directory. Authentication, naming client (IPNS) and upload client, are provided by web3.storage.

Authentication

To authenticate with web3.storage you must provide your web3StorageEmail address and a space (optional) to the configuration options.

If you don't have an account at this moment you can use the autoGenerateSpace property to generate a new space for you.

Be careful, this will generate a new space with every run, we recommend you to create an account using web3.storage

Usage

Configurations options are documented in the PublisherIpfsConfig file.

module.exports = {
  // ...
  publishers: [
    {
      name: "electron-forge-ipfs-publisher",
      config: {
        web3StorageEmail: process.env.WEB3_STORAGE_EMAIL,
        space: process.env.SPACE, // example: did:key:z6MkgkS7iCnKakvK6PTWtEWXQQEhXgwv4n8b7Vf1VibcaRyT
      },
    },
  ],
};

Key management

By default, the IPFS publisher will upload its objects to the {prefix}/{platform}/{arch}/{name} key, where:

{prefix} is the value of the config.folder option (defaults to the "name" field in your package.json).

{platform} is the target platform for the artifact you are publishing.

{arch} is the target architecture for the artifact you are publishing.

{name} is the file name of the artifact you are publishing.

If you run the Publish command multiple times on the same platform for the same version (e.g. simultaneously publishing ia32 and x64 Windows artifacts), your uploads can get overwritten in the IPFS directory.

To avoid this problem, you can use the keyResolver option to generate the IPFS key programmatically.

module.exports = {
  name: "electron-forge-ipfs-publisher",
  config: {
    // ...
    keyResolver: (fileName, platform, arch) => {
      return `some-prefix/${platform}/${arch}/${filename}`;
    },
    // ...
  },
};

Auto updating from IPFS

You can configure Electron's built-in autoUpdater module to use the artifacts published by the IPFS publisher. This is a four-step process:

First, you must configure electron-forge-ipfs-publisher to publish your files into an auto-updater compatible layout and use @electron-forge/maker-zip + @electron-forge/maker-squirrel to build your application.

    module.exports = {
    // ...
    makers: [
        {
        name: '@electron-forge/maker-zip',
        config: (arch) => ({
            // Note that we must provide the IPNS url here
            // in order to support smooth version transitions
            // by now you need to leave it empty
            macUpdateManifestBaseUrl: undefined
        })
        },
        {
        name: '@electron-forge/maker-squirrel',
        config: (arch) => ({
            // Note that we must provide this IPNS url here
            // in order to generate delta updates
            // by now you need to leave it empty
            remoteReleases: undefined
        })
        }
    ],
    publishers: [
        {
        name: 'electron-forge-ipfs-publisher',
        config: {
            ... // your config
        }
        }
    ]
    };

Then, run electron-forge publish to publish your application to IPFS the first time, this is a v0 publish.

It will generate new files in the root of yor project, these files are used by the publisher so you may not edit them:

• publications.json - contains the IPFS, IPNS and W3S CID's of the published application

  Note: You can use this CID to get the release artifacts. IPNS and W3S CID's are the paths that you need to use to request the release artifacts permanently through a IPFS gateway. IPFS CID's are the paths that you need to use to request the release artifacts for a specific version of your application.

• .w3name/name.key - contains the W3S/IPNS name private key, this key is used to publish IPNS values (versions of yor app). This key should not be shared with anyone, you may want to ignore it in your git repo.

Now you can update your makers config to use the update urls with the provided CID's:

    module.exports = {
    // ...
    makers: [
        {
        name: '@electron-forge/maker-zip',
        config: (arch) => ({
            // Note that we must provide the IPNS url here
            // in order to support smooth version transitions
            macUpdateManifestBaseUrl: `https://ipfs.io/ipfs/${ipfsCid}/my-app-updates/darwin/${arch}`,
        })
        },
        {
        name: '@electron-forge/maker-squirrel',
        config: (arch) => ({
            // Note that we must provide this IPNS url here
            // in order to generate delta updates
            remoteReleases: `https://ipfs.io/ipfs/${ipfsCid}/my-app-updates/win32/${arch}`,
        })
        }
    ],
    publishers: [
        {
        name: 'electron-forge-ipfs-publisher',
        config: {
            ... // your config
        }
        }
    ]
    };

With Forge configured correctly, the second step is to configure the autoUpdater module inside your app's main process. The simplest form is shown below but you might want to hook additional events to show UI to your user or ask them if they want to update your app right now.

const { updateElectronApp, UpdateSourceType } = require('update-electron-app');

updateElectronApp({
  updateSource: {
    type: UpdateSourceType.StaticStorage,
    baseUrl: `https://ipfs.io/ipfs/${ipfsCid}/my-app-updates/${process.platform}/${process.arch}`,
  }
});