@open-xchange/vite-plugin-project-meta 0.0.1

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.0.1] - 2024-07-30
+
+- initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OX Software GmbH, Germany <info@open-xchange.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @open-xchange/vite-plugin-project-meta
+
+A Vite plugin providing a virtual import for project metadata with build information.
+
+## Usage
+
+Add the plugin to your Vite configuration:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import metaPlugin from "@open-xchange/vite-plugin-project-meta"
+
+export default defineConfig(() => {
+
+  // ...
+
+  plugins: [
+    // ...
+
+    metaPlugin({
+      id: "my-project-ui"
+      name: "My Project UI",
+    }),
+  ],
+})
+```
+
+Register TypeScript type definitions for the "virtual:metadata" module import:
+
+```json
+// src/tsconfig.json
+
+{
+  // ...
+
+  "types": [
+    "vite/client",
+    "@open-xchange/vite-plugin-project-meta/virtual"
+  ],
+}
+```
+
+Use the virtual module in your code:
+
+```ts
+// src/path/to/some/module.ts
+
+import metadata from "virtual:metadata"
+
+console.log(metadata.id)        // from package.json ("name")
+console.log(metadata.name)      // from `options.projectName`
+console.log(metadata.version)   // from package.json ("version")
+console.log(metadata.builddate) // plugin execution timestamp
+console.log(metadata.commitsha) // from env variable "CI_COMMIT_SHA"
+```
+
+### Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `projectName` | `string` | _required_ | Display name of the project, for metadata property "name". |

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from "vite";
+/**
+ * Configuration options for the plugin "@open-xchange/vite-plugin-project-meta".
+ */
+export interface VitePluginProjectMetaOptions {
+    /**
+     * The display name of the project.
+     */
+    projectName: string;
+}
+export declare const PROJECT_NAME = "@open-xchange/vite-plugin-project-meta";
+/**
+ * Vite plugin that provides a virtual module "virtual:metadata" exporting a
+ * metadata object with project build information (timestamp, commit ID, etc.).
+ *
+ * @param options
+ *  Plugin configuration.
+ *
+ * @returns
+ *  The Vite plugin object.
+ */
+export default function vitePluginProjectMeta(options: VitePluginProjectMetaOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,49 @@
+/*
+* Copyright (C) Open-Xchange GmbH, Germany <info@open-xchange.com>
+*
+* This program is proprietary software and licensed to you under Open-Xchange
+* GmbH's Software License Agreement.
+*/
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+// constants ==================================================================
+export const PROJECT_NAME = "@open-xchange/vite-plugin-project-meta";
+// plugin =====================================================================
+/**
+ * Vite plugin that provides a virtual module "virtual:metadata" exporting a
+ * metadata object with project build information (timestamp, commit ID, etc.).
+ *
+ * @param options
+ *  Plugin configuration.
+ *
+ * @returns
+ *  The Vite plugin object.
+ */
+export default function vitePluginProjectMeta(options) {
+    const MODULE_NAME = "virtual:metadata";
+    const MODULE_ID = `\0${PROJECT_NAME}/${MODULE_NAME}`;
+    let metadata;
+    return {
+        name: PROJECT_NAME,
+        configResolved(config) {
+            const pkg = JSON.parse(readFileSync(join(config.root, "package.json"), { encoding: "utf8" }));
+            metadata = {
+                id: pkg.name,
+                name: options.projectName,
+                version: pkg.version,
+                builddate: new Date().toISOString(),
+                commitsha: process.env.CI_COMMIT_SHA,
+            };
+        },
+        resolveId(source) {
+            return (source === MODULE_NAME) ? MODULE_ID : null;
+        },
+        load(id) {
+            if (id !== MODULE_ID) {
+                return null;
+            }
+            const code = `export default ${JSON.stringify(metadata)};`;
+            return { code, map: { mappings: "" } };
+        },
+    };
+}

package/dist/virtual.d.ts

@@ -0,0 +1,37 @@
+declare module "virtual:metadata" {
+
+    /**
+     * Shape of the metadata object provided by the virtual module "virtual:metadata".
+     */
+    export interface VirtualProjectMetadata {
+
+        /**
+         * Internal identifier of the project.
+         */
+        id: string;
+
+        /**
+         * The display name of the project.
+         */
+        name: string;
+
+        /**
+         * The version string of the package.
+         */
+        version: string;
+
+        /**
+         * The date when the package was built (ISO timestamp).
+         */
+        builddate: string;
+
+        /**
+         * The identifier of the last GIT commit the package has been built on.
+         * Will be picked from the environment variable "CI_COMMIT_SHA".
+         */
+        commitsha: string | undefined;
+    }
+
+    const metadata: VirtualProjectMetadata;
+    export default metadata;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@open-xchange/vite-plugin-project-meta",
+    "version": "0.0.1",
+    "description": "Vite plugin providing a virtual import for project metadata",
+    "repository": {
+        "url": "https://gitlab.open-xchange.com/fspd/npm-packages/vite-plugin-project-meta"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": "18.18.0 || ^20.9.0 || >=21.1.0"
+    },
+    "packageManager": "yarn@4.3.1",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./virtual": {
+            "types": "./dist/virtual.d.ts"
+        }
+    },
+    "scripts": {
+        "prepare": "husky",
+        "prepack": "yarn build && yarn lint",
+        "build": "npx --yes rimraf dist && tsc && cpy --flat src/virtual.d.ts dist/",
+        "lint": "eslint ."
+    },
+    "lint-staged": {
+        "*.{js,ts,json}": "yarn lint"
+    },
+    "devDependencies": {
+        "@open-xchange/linter-presets": "0.1.11",
+        "@types/node": "20.14.13",
+        "cpy-cli": "5.0.0",
+        "eslint": "9.8.0",
+        "husky": "9.1.4",
+        "typescript": "5.5.4",
+        "vite": "5.3.5"
+    },
+    "peerDependencies": {
+        "vite": "^5.3"
+    },
+    "resolutions": {
+        "semver": "^7.6.2"
+    }
+}