Jak zobrazit verzi aplikace z package.json

1. Proč má být verze vidět přímo v aplikaci

Verze aplikace v uživatelském rozhraní odpovídá na první otázku podpory: jakou verzi máte? Když číslo verze není nikde vidět, zjistí ho jen DevOps z nasazení nebo vývojář z kódu. Podpora pak řeší nahlášenou chybu, aniž ví, jestli už není v novější verzi opravená.

Obvyklá místa pro umístění verze jsou patička aplikace, obrazovka Nastavení, položka Nápověda → O aplikaci a chybová stránka. U interních nástrojů stačí patička, u aplikací pro zákazníky se hodí i obrazovka O aplikaci s kontaktem na podporu.

2. Odkud verzi vzít

Číslo verze má mít jeden zdroj, ze kterého ho build převezme. U JavaScriptových projektů je to pole version v package.json, které mění příkaz npm version nebo nástroj na vydávání verzí. Jaké schéma čísel zvolit popisuje článek Verzování aplikací.

Do klientského kódu nepatří celý package.json. Obsahuje seznam závislostí a skriptů, které uživatel aplikace vidět nemusí. Proto build vkládá jen samotný řetězec verze, jak ukazují příklady níže.

3. Vite: React, Vue i Svelte

Ve Vite verzi z package.json vložíte volbou "define" ve vite.config.ts. Vite při buildu nahradí každý výskyt __APP_VERSION__ v kódu řetězcem verze, takže do balíčku se nedostane nic dalšího. Proměnnou npm_package_version nastaví npm, pnpm i Yarn při spuštění skriptu, tedy při npm run dev a npm run build.

V TypeScriptu ještě do src/vite-env.d.ts přidejte řádek declare const __APP_VERSION__: string;. V komponentě pak verzi použijete jako běžnou konstantu, například <footer>Verze {__APP_VERSION__}</footer>.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  define: {
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version),
  },
});

4. Next.js

V Next.js verzi předáte polem "env" v next.config.ts. Next.js hodnoty z "env" vloží do kódu při buildu, takže process.env.NEXT_PUBLIC_APP_VERSION funguje v serverových i klientských komponentách. Import package.json v konfiguraci se do klientského balíčku nedostane, konfigurace běží jen při buildu.

import type { NextConfig } from "next";
import pkg from "./package.json";

const nextConfig: NextConfig = {
  env: {
    NEXT_PUBLIC_APP_VERSION: pkg.version,
  },
};

export default nextConfig;

5. Angular

V Angularu načtete verzi z package.json pojmenovaným importem pole "version". V tsconfig.json k tomu musí být zapnutá volba "resolveJsonModule". Výchozí builder Angularu (esbuild) z JSON souboru ponechá v balíčku jen importované pole, ne celý package.json.

import { Component } from "@angular/core";
import { version } from "../../package.json";

@Component({
  selector: "app-footer",
  template: `<footer>Verze {{ version }}</footer>`,
})
export class AppFooter {
  readonly version = version;
}

6. Číslo sestavení a commit z CI/CD

Číslo sestavení nebo hash commitu do package.json nepatří, zná je až CI/CD pipeline. Předejte je při buildu jako proměnnou prostředí. Ve Vite se do kódu dostanou proměnné s předponou VITE_, například VITE_BUILD_NUMBER=$GITHUB_RUN_NUMBER npm run build v GitHub Actions, a v kódu je přečtete z import.meta.env.VITE_BUILD_NUMBER. V Next.js má stejnou roli předpona NEXT_PUBLIC_.

Když verzi berete z Git tagu, odstraňte z ní předponu v. Číslo 1.4.2 a tag v1.4.2 jsou pro uživatele totéž, pro porovnání verzí v nástrojích ale ne.

7. Verze s poznámkami k vydání v AboutTheApp

Samotné číslo verze neřekne, co se v ní změnilo. Poznámky k vydání přitom bývají roztroušené v commitech, pull requestech a tascích, kam se uživatel nebo podpora nedostane. About box z AboutTheApp má variantu vzhledu "Verze a novinky", která ukáže verzi a po rozbalení také poznámky k vydání.

Variantu vzhledu "Nápověda a podpora" ocení podpora: obsahuje tlačítko "Zkopírovat informace o aplikaci" pro zkopírování názvu a verze do schránky, které uživatel vloží do hlášení chyby. Obecný postup vložení About boxu do vaší aplikace popisuje návod pro React.

1. 1

   Založte produkt

   V AboutTheApp vytvořte produkt nebo otevřete existující a na jeho kartě klikněte na "Integrovat".

2. 2

   Zvolte variantu vzhledu a zkopírujte její kód pro vložení

   Ve volbě "Varianta" vyberte "Verze a novinky". Panel připraví skript a element about-the-app s aliasem vaší aplikace, který vložíte do zdrojového kódu vaší aplikace.

3. 3

   Doplňte atribut version

   Do zdrojového kódu elementu přidejte atribut "version" s hodnotou z buildu, například version={__APP_VERSION__} ve Vite nebo version={process.env.NEXT_PUBLIC_APP_VERSION} v Next.js.

4. 4

   Zapisujte verze s poznámkami

   Každou vydanou verzi zapište do katalogu verzí produktu v dashboardu nebo pomocí CI/CD voláním POST /integrations/versions. Pro GitHub Actions je připravena akce Report release to AboutTheApp.

export function AppFooter() {
  return <about-the-app alias="my-app" variant="version" version={__APP_VERSION__} />;
}

Časté otázky