🔔 version-rocket 🚀

English | 简体中文

Notify users when a new version of your site is available and prompt them to refresh the page. When you finish deploying your app, send a deployment message to Lark or WeCom Group Chat

About

version-rocket checks the version in the user's current browser against the version file in the remote server.

If a new version is available, a new version update prompt will be displayed to and the user will be given an operation button to refresh the page. Alternatively, version-rocket can notify you by receiving a callback function to support custom user interface.

We use the Web Worker API based on javascript to do the polling loop, will not affect the browser rendering process.

Features

• Support all modern browsers
• Available version real-time monitoring, support any version format, such as: 1.1.0, 1.1.1.0, 1.1.0-beta, etc.
• Support personalized version popup text and theme, also support custom UI
• Sync deployment message to Lark or WeCom group chat after successful deploy
• Card text and templates for deployment messages support customization, and support the dynamically generated fields.
• Support TypeScript
• Npm package support

Screenshots

• The first picture prompts user to refresh the page.
• The second picture personalize the popup text and theme, great for when you need to customize the text and theme.
• The third picture shows that after the successful deployment of the project, the deployment message will be sent to the Lark group chat to inform the team members. custom message card text, can be set whether @all, and support dynamic generation of field incoming (such as version generated after ci/cd, support dynamic incoming)
• The fourth picture shows that after the successful deployment of project, the deployment message will be send to the WeCom group chat to inform the team members... the functions and custom fields are the same as lark.

Usage

Install

Get Started

Install the latest version, use checkVersion function, this function compatible with pollingCompareVersion, and support customize popup text and theme (Recommended)

Use the default theme

// 1. Step one: import checkVersion(), and use
import { checkVersion } from 'version-rocket'
// By default, it is recommended to use the version field in package.json, and if there is a custom version, ignore this line
import { version } from '../package.json'

checkVersion({
  localPackageVersion: version,
  originVersionFileUrl: `${location.origin}/version.json`,
})
 

/**
 * 2. Step two:
 * generate-version-file shortcut command to create the version.json file.
 * 
 * VERSION (optional): By default, the version.json file is generated using the version in package.json, if you need to customize the version, you can pass in the environment variable VERSION to define
 * 
 * The parameter is the directory where you want to create version.json. If you don't pass the parameter, it will be created in the dist directory by default.
*/ 

{
  "name": "test",
  "description": "test",
  "private": true,
  "version": "0.0.1",
  "scripts": {
    ...
    "generate:version": "VERSION=1.1.0-beta generate-version-file dist public"
    ...
  },
  ...
}

// nginx example

server {
  ...
  location / {
    ...
    if ($request_filename ~* .*\/version\.(json)$) {
      add_header Cache-Control "private, no-store, no-cache, must-revalidate, proxy-revalidate";
    }
    ...
  }
  ...
}

Complete the above two steps, the version monitoring function can be used normally 🎉🎉

Personalize popup text and theme

import { checkVersion } from 'version-rocket'
import { version } from '../package.json'

checkVersion(
  {
    localPackageVersion: version,
    originVersionFileUrl: `${location.origin}/version.json`,
  },
  {
    title: 'Title',
    description: 'Description',
    primaryColor: '#758bfd',
    rocketColor: '#ff8600',
    buttonText: 'Button Text',
  }
)

Personalize popup image

import { checkVersion } from 'version-rocket'
import { version } from '../package.json'

checkVersion(
  {
    localPackageVersion: version,
    originVersionFileUrl: `${location.origin}/version.json`,
  },
  {
    imageUrl: 'https://avatars.githubusercontent.com/u/26329117',
  }
)

If you are using version 1.0.9 and later, call the pollingCompareVersion method

It is recommended to upgrade to the latest version and experience the function of customizing popup text and theme

// 1. Step one: import pollingCompareVersion, and use
import { pollingCompareVersion } from 'version-rocket'
import { version } from '../package.json'

pollingCompareVersion(version, `${location.origin}/version.json`, 30000, (data) => {
    console.log(data)
})

// 2. Step two: see above: "Use the default theme"

See "Attributes/Parameters" table for more personalized settings📄

Support push notification of successful deployment to Lark group chat

/**
 * 1. Step one:
 * You need to create a lark-message-config.json file first, it store the field for setting the text for the message card. 
 * 
 * Then, you can just execute the send-lark-message shortcut command. By default, the lark-message-config.json file in the current path is selected.
 * 
 * MESSAGE_PATH (optional): If you want to customize the file path and file name, you can set the MESSAGE_PATH parameter to pass it in.
 * 
 * PACKAGE_JSON_PATH (optional): If you want to customize the path to the package.json file, you can do so by passing in the PACKAGE_JSON_PATH environment variable. We will get the package.json file from the root path by default.
*/

{
  "name": "test",
  "description": "test",
  "private": true,
  "version": "0.0.1",
  "scripts": {
    ...
    "send-lark-message:test": "MESSAGE_PATH=./lark-message-config.json PACKAGE_JSON_PATH=./packages/test/package.json send-lark-message"
    ...
  },
  ...
}

// Step two: lark-message-config.json example
{
    // card title
    "title": "TEST FE Deployed Successfully",
    // project name label
    "projectNameLabel": "Project name label",
    // deploy project name
    "projectName": "TEST",
    // project branch label
    "branchLabel": "Branch label",
    // deploy branch name
    "branch": "Staging",
    // version label
    "versionLabel": "Version label",
    // version
    "version": "1.1.1.0",
    // project access url label
    "accessUrlLabel": "Access URL label",
    // project access url
    "accessUrl": "https://test.com",
    // remind group chat members label
    "isNotifyAllLabel": "Is notify all label",
    // remind group chat members: true/false
    "isNotifyAll": true,
    // lark robot webhook url
    "larkWebHook": "https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxx",
    // deploy type description
    "deployToolsText": "Deploy tools text",
    // deploy type
    "deployTools": "Jenkins",
    // the deploy time zone that you want to display, default "Asia/Shanghai"
    "expectConvertToTimezone": "America/New_York"
    // more information want to show
    "remark": "Trigger by bob, fix xxx bug"
}

Support push notification of successful deployment to WeCom group chat

/**
 * 1. Step one:
 * You need to create a message-config.json file first, it store the field for setting the text for the message card. 
 * 
 * Then, you can just execute the send-wecom-message shortcut command. By default, the message-config.json file in the current path is selected.
 * 
 * MESSAGE_PATH (optional): If you want to customize the file path and file name, you can set the MESSAGE_PATH parameter to pass it in.
 * 
 * PACKAGE_JSON_PATH (optional): If you want to customize the path to the package.json file, you can do so by passing in the PACKAGE_JSON_PATH environment variable. We will get the package.json file from the root path by default.
*/

{
  "name": "test",
  "description": "test",
  "private": true,
  "version": "0.0.1",
  "scripts": {
    ...
    "send-wecom-message:test": "MESSAGE_PATH=./message-config.json PACKAGE_JSON_PATH=./packages/test/package.json send-wecom-message"
    ...
  },
  ...
}

// Step two: message-config.json example
{
    // card title
    "title": "TEST FE Deployed Successfully",
    // project name label
    "projectNameLabel": "Project name label",
    // deploy project name
    "projectName": "TEST",
    // project branch label
    "branchLabel": "Branch label",
    // deploy branch name
    "branch": "Staging",
    // version label
    "versionLabel": "Version label",
    // version
    "version": "1.1.1.0",
    // project access url label
    "accessUrlLabel": "Access URL label",
    // project access url
    "accessUrl": "https://test.com",
    // remind group chat members label
    "isNotifyAllLabel": "Is notify all label",
    // remind group chat members: true/false
    "isNotifyAll": true,
    // WeCom robot webhook url
    "webHook": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxxxxxxxxx",
    // deploy type description
    "deployToolsText": "Deploy tools text",
    // deploy type
    "deployTools": "Jenkins",
    // the deploy time zone that you want to display, default "Asia/Shanghai"
    "expectConvertToTimezone": "America/New_York"
    // more information want to show
    "remark": "Trigger by bob, fix xxx bug"
}

Supports incoming dynamically generated card copy

When the card text is dynamically generated based on the condition, you can pass in MESSAGE_JSON field to define, Note: the value of MESSAGE_JSON needs to be escaped

  /**
   * MESSAGE_JSON (optional): If the card text will be generated according to the conditions, you can pass in MESSAGE_JSON field to customize (this parameter is very useful for applications that dynamically generate card text, such as version, title, etc.)
  */
  
  // Lark
  {
    "name": "test",
    "description": "test",
    "private": true,
    "version": "0.0.1",
    "scripts": {
      ...
      "send-lark-message:test": "MESSAGE_JSON='{\"title\":\"This is a dynamically generated title\",\"version\":\"1.1.0-beta\",\"accessUrl\":\"http://test.example.com\",\"isNotifyAll\":true}' send-lark-message"
      ...
    },
    ...
  }

   // WeCom
  {
    "name": "test",
    "description": "test",
    "private": true,
    "version": "0.0.1",
    "scripts": {
      ...
      "send-wecom-message:test": "MESSAGE_JSON='{\"title\":\"This is a dynamically generated title\",\"version\":\"1.1.0-beta\",\"accessUrl\":\"http://test.example.com\",\"isNotifyAll\":true}' send-wecom-message"
      ...
    },
    ...
  }

// Or, after exporting the variable, reference it in package.json

// ci file
sh "npm run build"
sh "export messageJSON='{\"title\": \"This is a title\"}'"

// package.json

  // Lark
  {
    "name": "test",
    "description": "test",
    "private": true,
    "version": "0.0.1",
    "scripts": {
      ...
      "send-lark-message:test": "MESSAGE_JSON=${messageJSON} send-lark-message"
      ...
    },
    ...
  }
  
  // WeCom
  {
    "name": "test",
    "description": "test",
    "private": true,
    "version": "0.0.1",
    "scripts": {
      ...
      "send-wecom-message:test": "MESSAGE_JSON=${messageJSON} send-wecom-message"
      ...
    },
    ...
  }

Personalize the deployment message template

// Lark: lark-message-config.json example
{
    // message card template content
    "message": {
        "msg_type": "text",
        "content": {
            "text": "New message reminder"
        }
    },
    // webhook link for the Lark bot
    "larkWebHook": "https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxx"
}
 
// WeCom: message-config.json example
{
    // message card template content
    "message": {
        "msgtype": "text",
        "text": {
            "content": "This is a custom message"
        }
    },
    // webhook link for the WeCom bot
    "webHook": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxxxxxx"
}

Attributes/Parameters

checkVersion function parameter table

pollingCompareVersion function parameter table

Link

• Timezone List
• JSON Escape

License

version-rocket is open source software with Apache License 2.0