Provide VERSION file with asset bundle, read in application (#3148)

* Add documentation / comments on new build options

.gitignore

@@ -6,3 +6,4 @@ node_modules
 /flow-typed
 .vscode
 bash
+public/VERSION

README.md

@@ -12,6 +12,10 @@ Kinto-based systems.
 
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
+     - [Prebuilt Single Server Assets](#prebuilt-single-server-assets)
+     - [Building the Assets](#building-the-assets)
+        - [Latest Release](#latest-release)
+        - [Earlier Release](#earlier-release)
   - [Build customization](#build-customization)
      - [Single Server](#single-server)
      - [Building for relative paths](#building-for-relative-paths)
@@ -22,6 +26,12 @@ Kinto-based systems.
      - [Browser support](#browser-support)
      - [How to display a nested field value using the collection displayFields property?](#how-to-display-a-nested-field-value-using-the-collection-displayfields-property)
   - [Releasing](#releasing)
+     - [Through GitHub UI](#through-github-ui)
+     - [Through git commands](#through-git-commands)
+  - [Deploying to github-pages](#deploying-to-github-pages)
+     - [Repo configuration for forks](#repo-configuration-for-forks)
+     - [Deployed automatically on release publish](#deployed-automatically-on-release-publish)
+     - [Running the github action manually](#running-the-github-action-manually)
   - [License](#license)
 
 ---
@@ -37,20 +47,40 @@ pre-commit`` and ``pre-commit install``. (If you have a
 
 ## Installation
 
-The easiest way to install and use Kinto Admin on your server is to:
-- download a [release](https://github.com/Kinto/kinto-admin/releases/) from Github.
+### Prebuilt Single Server Assets
+If you intend to use Kinto Admin in a Kinto Server with standard options, since [version v3.0.3](https://github.com/Kinto/kinto-admin/releases/tag/v3.0.3), you can download prebuilt assets for each release. 
+
+### Building the Assets
+To customize your Kinto Admin installation, you can download the source code and build the asset bundle. Then, you can serve the bundle from your server of choice. See [below](#build-customization) for customization options.
+
+#### Latest Release
+- download the latest [release](https://github.com/Kinto/kinto-admin/releases/latest) from Github.
 
 - Unzip the directory, then install dependencies:
-```
-$ cd kinto-admin && npm install
+``` 
+$ cd kinto-admin && npm ci
 ```
 
 - Build the static bundle with:
+
 ```
 $ npm run build
 ```
 
-This will generate a production-ready assets in a `build` directory, ready to be served from your server of choice.
+#### Earlier Release
+To download an earlier release, set a `KINTO_ADMIN_VERSION` environment variable with the tag you're downloading. For example:
+
+```bash
+export KINTO_ADMIN_VERSION="v1.2.3"
+
+curl -OL "https://github.com/Kinto/kinto-admin/archive/refs/tags/${KINTO_ADMIN_VERSION}.tar.gz"
+# ...
+npm ci
+npm run build
+```
+
+This will inject the version into the built asset bundle.
+
 
 ## Build customization
 Use the following options to customize the Kinto Admin build.
@@ -59,14 +89,14 @@ Use the following options to customize the Kinto Admin build.
 By default, Kinto Admin gives you the option to connect to multiple Kinto Servers. If you only want Kinto Admin to connect to the server from which it's being served, you can set the `KINTO_ADMIN_SINGLE_SERVER` flag as an environment variable:
 
 ```
-KINTO_ADMIN_SINGLE_SERVER=1 npm run build
+$ KINTO_ADMIN_SINGLE_SERVER=1 npm run build
 ```
 
 ### Building for relative paths
-By default, Kinto Admin assumes assets will be served from the root path (`/`) of the server. If you'd like to serve assets from a different location, set that option with an `ASSET_PATH` environment variable:
+By default, Kinto Admin assumes assets will be served from the root path (`/`) of the server. If you'd like to serve assets from a different location, set that option with the `ASSET_PATH` environment variable:
 
 ```
-ASSET_PATH="/some/prefix/" npm run build
+$ ASSET_PATH="/some/prefix/" npm run build
 ```
 
 ## Hacking on kinto-admin
@@ -86,10 +116,13 @@ $ cd kinto-admin && npm install
 Optionally, configure `git` to use `.git-blame-ignore-revs` to remove noisy commits (e.g. running `prettier` on the entire codebase) from `git blame`:
 
 ```
-git config blame.ignoreRevsFile .git-blame-ignore-revs
+$ git config blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
 After installation of packages, run the development server.
+```
+$ npm run start
+```
 
 ## Development server
 
@@ -101,7 +134,7 @@ install Kinto Admin using the installation instructions above.
 To run in development mode:
 
 ```
-$ npm start
+$ npm run start
 ```
 
 The application is served at [localhost:3000](http://localhost:3000/), and any

bin/generate-version.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { writeFileSync } from "fs";
+import fetch from "node-fetch";
+
+async function getLatestReleaseVersion() {
+  const res = await fetch(
+    "https://api.github.com/repos/Kinto/kinto-admin/releases/latest",
+    { headers: { "user-agent": "Kinto Admin CI" } } // `user-agent` header required by Github API
+  );
+  const body = await res.json();
+  return body.tag_name.replace(/^v/, "");
+}
+
+const getGitVersion = () => {
+  try {
+    return execSync("git describe --tags --abbrev=4", {
+      encoding: "utf-8",
+    })
+      .trim()
+      .replace(/^v/, "");
+  } catch (error) {
+    console.log(error);
+  }
+};
+
+(async () => {
+  /**
+   * The `KINTO_ADMIN_VERSION` env var is used when someone wants to download
+   * an earlier release and build assets from source. Since they won't be in a
+   * `git` directory to be able to pull version information from the latest
+   * tag, this allows them to inject the version they're downloading into the bundle.
+   */
+  const version =
+    process.env.KINTO_ADMIN_VERSION ||
+    getGitVersion() ||
+    (await getLatestReleaseVersion());
+
+  writeFileSync("./public/VERSION", version);
+})();

package.json

@@ -4,16 +4,17 @@
   "description": "Kinto Web Administration Console in React.js",
   "type": "module",
   "scripts": {
-    "build": "vite build",
+    "build": "npm run generate-version && vite build",
     "build:readme": "toctoc README.md -w",
-    "build:kinto-single": "ASSET_PATH=/v1/admin KINTO_ADMIN_SINGLE_SERVER=1 vite build",
-    "cs-check": "prettier -l \"{src,test}/**/*.{js,jsx,ts,tsx}\"",
-    "cs-format": "prettier \"{src,test}/**/*.{js,jsx,ts,tsx}\" --write",
+    "build:kinto-single": "ASSET_PATH=/v1/admin KINTO_ADMIN_SINGLE_SERVER=1 npm run build",
+    "cs-check": "prettier -l \"{src,test,bin}/**/*.{js,jsx,ts,tsx}\"",
+    "cs-format": "prettier \"{src,test,bin}/**/*.{js,jsx,ts,tsx}\" --write",
+    "generate-version": "node ./bin/generate-version.js",
     "lint": "eslint . --ext ts,tsx",
     "preview": "vite preview",
-    "start": "vite",
+    "start": "npm run generate-version && vite",
     "tdd": "vitest",
-    "test": "vitest --watch=false",
+    "test": "npm run generate-version && vitest --watch=false",
     "test:ci": "npm run test",
     "test-all": "npm run lint && npm run test",
     "test-all:ci": "npm run lint && npm run test:ci"
@@ -63,6 +64,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-react": "^7.33.2",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "node-fetch": "^3.3.2",
     "prettier": "^3.0.2",
     "toctoc": "^0.4.0",
     "typescript": "^5.3.3",

vite.config.ts

@@ -2,7 +2,7 @@
 
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
-import { execSync } from 'child_process'
+import { readFileSync } from 'fs'
 import path from 'path'
 
 /**
@@ -13,7 +13,7 @@ import path from 'path'
  */
 const ASSET_PATH = process.env.ASSET_PATH || "/";
 
-const KINTO_ADMIN_VERSION = execSync('git describe --tags --abbrev=4').toString().replace(/^v|\n/g, '');
+const KINTO_ADMIN_VERSION = readFileSync('./public/VERSION').toString();
 
 // https://vitejs.dev/config/
 export default defineConfig({