@open-xchange/vite-plugin-replace-pkg 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-08-06
+
+- 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,179 @@
+# @open-xchange/vite-plugin-replace-pkg
+
+A Vite plugin that replaces a specific external package with an arbitrary source code module.
+
+## Usage
+
+This plugin replaces a specific external package with a custom source file that can be downloaded from an arbitrary URL, or that can be extracted from a GitLab project repository. If the replacement source file cannot be resolved, the original external package will be used.
+
+A common use case is replacing a public package with an internally hosted commercial version of the package. When building the product internally, the internal version of the package will be bundled, otherwise the public version.
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+export default defineConfig(() => {
+  plugins: [
+    replacePlugin({
+      package: "external-package",
+      replace: "https://example.org/path/to/index.js",
+    }),
+  ],
+})
+```
+
+```ts
+// src/index.ts
+
+import * as ext from "external-package" // imports replacement if available
+```
+
+It is possible to replace different packages by instantiating this plugin multiple times:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+export default defineConfig(() => {
+  plugins: [
+    replacePlugin({
+      package: "external-package",
+      replace: "https://example.org/path/to/index.js",
+    }),
+    replacePlugin({
+      package: "@namespace/another-package",
+      replace: { /* GitLab project file */ },
+    }),
+  ],
+})
+```
+
+### Options
+
+#### `package`
+
+- Type: `string`
+- _required_
+
+The name of the external package to be replaced, as appearing in `import` statements in source code.
+
+#### `replace`
+
+- Type: _various (see below)_
+- _required_
+
+The location of the source file to resolve the module imports with. There are different ways to declare the source file:
+
+1. A simple URL as `string` (see above for an example).
+
+2. A [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) configuration object for the `fetch` function (headers, body, etc.), with the following additional options:
+
+   | Name | Type | Default | Description |
+   | - | - | - | - |
+   | `url` | `string` | _required_ | The URL of the source file to be downloaded. |
+   | `query` | `Dict<string\|number\|boolean>` | `{}` | Query parameters to be added to the URL. |
+
+   Example:
+
+   ```ts
+   // vite.config.ts
+
+   import { defineConfig } from "vite" // or "vitest/config"
+   import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+   export default defineConfig(() => {
+     plugins: [
+       replacePlugin({
+         package: "external-package",
+         replace: {
+           method: "POST",
+           headers: { "X-Some-Header", "abc" },
+           url: "https://example.org/api/to/endpoint",
+           query: { ts: Date.now() },
+         },
+       }),
+     ],
+   })
+   ```
+
+3. A specification for a file in a GitLab project repository, with the following options:
+
+   | Name | Type | Default | Description |
+   | - | - | - | - |
+   | `server` | `string` | _required_ | The URL of the GitLab server to be used for downloading the source file. |
+   | `project` | `string\|number` | _required_ | Name or numeric identifier of the GitLab project. The project name may contain slashes (e.g. `"my-group/my-project"`) which will be encoded internally. |
+   | `path` | `string` | _required_ | Path to the source file to be downloaded. Slashes in the path will be encoded internally. |
+   | `ref` | `string` | `HEAD` | The name of a branch or tag, or a commit ID. Slashes in branch names will be encoded internally. |
+
+   Example:
+
+   ```ts
+   // vite.config.ts
+
+   import { defineConfig } from "vite" // or "vitest/config"
+   import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+   export default defineConfig(() => {
+     plugins: [
+       replacePlugin({
+         package: "external-package",
+         replace: {
+           server: "https://gitlab.example.org",
+           project: "internals/commercial-package",
+           path: "path/to/index.js",
+           ref: "feature/branch-2",
+         },
+       }),
+     ],
+   })
+   ```
+
+4. A custom callback function. Will be invoked with the original package name (the value of the option `package`), and returns the source code to be used instead.
+
+   Example:
+
+   ```ts
+   // vite.config.ts
+
+   import { defineConfig } from "vite" // or "vitest/config"
+   import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+   export default defineConfig(() => {
+     plugins: [
+       replacePlugin({
+         package: "external-package",
+         async replace() { /* ... */ },
+       }),
+     ],
+   })
+   ```
+
+#### `transform`
+
+- Type: `(source: string) => string | string[] | Promise<string | string[]>`
+- _optional_
+
+Transformation filter for the source code. The function will be invoked with the downloaded source code, and returns the transformed source code to be used. An array of strings will be concatenated with newline characters.
+
+Example:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import replacePlugin from "@open-xchange/vite-plugin-replace-pkg"
+
+export default defineConfig(() => {
+  plugins: [
+    replacePlugin({
+      package: "external-package"
+      replace: "https://example.org/path/to/index.js",
+      transform: source => ["/* replaced file header */", source],
+    }),
+  ],
+})
+```

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import type { Plugin } from "vite";
+import type { Dict } from "@open-xchange/vite-helper/utils";
+/**
+ * The configuration options for the `fetch` function needed to download a
+ * source file.
+ */
+export interface VitePluginReplacePkg_RequestInit extends RequestInit {
+    /**
+     * The URL of the source file to be downloaded.
+     */
+    url: string;
+    /**
+     * Query parameters to be added to the URL.
+     */
+    query?: Dict<string | number | boolean>;
+}
+/**
+ * The specification of a source file in a GitLab repository.
+ *
+ * Downloading the source file needs a valid GitLab API token stored in the
+ * environment variable "GITLAB_TOKEN". If the variable does not exist,
+ * downloading the source wile will be skipped.
+ */
+export interface VitePluginReplacePkg_GitLabFile {
+    /**
+     * The URL of the GitLab server to be used for downloading the source file.
+     */
+    server: string;
+    /**
+     * Name or identifier of the GitLab project (repository). The project name
+     * may contain slashes (e.g. "my-group/my-project") which will be encoded
+     * internally.
+     */
+    project: string | number;
+    /**
+     * Path to the source file to be downloaded. Slashes in the path will be
+     * encoded internally.
+     */
+    path: string;
+    /**
+     * The name of a branch or a tag, or a commit ID. Slashes in branch names
+     * will be encoded internally. Default value is "HEAD".
+     */
+    ref?: string;
+}
+/**
+ * A custom callback function to fetch the replacement source code for an
+ * external package.
+ */
+export type VitePluginReplacePkg_Callback = (pkgName: string) => string | Promise<string>;
+/**
+ * Configuration options needed to replace an external package.
+ */
+export interface VitePluginReplacePkgOptions {
+    /**
+     * The name of the external package to be replaced.
+     */
+    package: string;
+    /**
+     * The location of the source file to resolve the module import with. Can
+     * be a simple URL as string, a configuration object for the `fetch`
+     * function (with URL, headers, etc.), a specification for a file in a
+     * GitLab project repository, or a custom callback function.
+     */
+    replace: string | VitePluginReplacePkg_RequestInit | VitePluginReplacePkg_GitLabFile | VitePluginReplacePkg_Callback;
+    /**
+     * Transformation filter for the downloaded source code.
+     *
+     * @param source
+     *  The downloaded source code.
+     *
+     * @returns
+     *  The transformed source code to be used, as plain string, or as array of
+     *  multiple source lines.
+     */
+    transform?: (source: string) => string | string[] | Promise<string | string[]>;
+}
+export declare const PROJECT_NAME = "@open-xchange/vite-plugin-replace-pkg";
+/**
+ * A plugin for Vite to replace a specific external package with an arbitrary
+ * source code module. If download of a requested source file fails for any
+ * reason, the plugin will step back silently, and the original package will be
+ * imported instead.
+ *
+ * @param options
+ *  The plugin configuration.
+ *
+ * @returns
+ *  The plugin instance.
+ */
+export default function vitePluginReplacePkg(options: VitePluginReplacePkgOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,111 @@
+import { onceFn } from "@open-xchange/vite-helper/utils";
+import { Logger } from "@open-xchange/vite-helper/logger";
+// constants ==================================================================
+export const PROJECT_NAME = "@open-xchange/vite-plugin-replace-pkg";
+const logger = new Logger({
+    loggerPrefix: "pkg",
+    logLevelEnvVar: "PLUGIN_REPLACE_PACKAGES_LOGLEVEL",
+});
+// functions ==================================================================
+const resolveFetchOptions = (options) => {
+    const { replace } = options;
+    // callback function
+    if (typeof replace === "function") {
+        return;
+    }
+    // plain string
+    if (typeof replace === "string") {
+        return replace ? { url: replace } : undefined;
+    }
+    // `RequestInit` object
+    if ("url" in replace) {
+        return replace.url ? replace : undefined;
+    }
+    // `GitLabFile` object
+    if ("project" in replace) {
+        // resolve GitLab API tokens
+        const token = process.env.GITLAB_TOKEN;
+        if (!token) {
+            logger.warn("missing environment variable %f with GitLab API token", "GITLAB_TOKEN");
+            return;
+        }
+        // build the file URL for the GitLab API
+        // https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository
+        const project = encodeURIComponent(replace.project);
+        const path = encodeURIComponent(replace.path);
+        const url = `${replace.server}/api/v4/projects/${project}/repository/files/${path}/raw`;
+        // additional settings (query, headers, etc.)
+        const query = { lfs: true };
+        if (replace.ref) {
+            query.ref = replace.ref;
+        }
+        const headers = { "PRIVATE-TOKEN": token };
+        return { url, headers, query };
+    }
+    logger.error("invalid configuration for package %f", options.package);
+    return undefined;
+};
+// plugin =====================================================================
+/**
+ * A plugin for Vite to replace a specific external package with an arbitrary
+ * source code module. If download of a requested source file fails for any
+ * reason, the plugin will step back silently, and the original package will be
+ * imported instead.
+ *
+ * @param options
+ *  The plugin configuration.
+ *
+ * @returns
+ *  The plugin instance.
+ */
+export default function vitePluginReplacePkg(options) {
+    const pkgName = options.package;
+    const moduleId = "\0" + PROJECT_NAME + "/" + pkgName;
+    const fetchSourceFile = onceFn(async () => {
+        try {
+            if (typeof options.replace === "function") {
+                return await options.replace(pkgName);
+            }
+            const fetchOptions = resolveFetchOptions(options);
+            if (fetchOptions) {
+                const query = Object.entries(fetchOptions.query ?? {}).map(entry => entry.map(encodeURIComponent).join("=")).join("&");
+                const url = fetchOptions.url + (query ? `?${query}` : "");
+                logger.info("requesting package %f from %f", pkgName, url);
+                const response = await fetch(url, fetchOptions);
+                if (response.ok) {
+                    return await response.text();
+                }
+                logger.warn(`requesting package %f failed: ${response.status} ${response.statusText}`, pkgName);
+            }
+            else {
+                logger.info("no replacement available for package %f", pkgName);
+            }
+        }
+        catch (error) {
+            logger.warn(`requesting package %f failed: ${error.message}`, pkgName);
+        }
+        return "";
+    });
+    // create and return the plugin object
+    return {
+        name: PROJECT_NAME,
+        resolveId: {
+            order: "pre",
+            async handler(source) {
+                if (source !== pkgName) {
+                    return;
+                }
+                const contents = await fetchSourceFile();
+                return contents ? moduleId : undefined;
+            },
+        },
+        async load(id) {
+            if (id !== moduleId) {
+                return;
+            }
+            const contents = await fetchSourceFile();
+            const transformed = options.transform ? await options.transform(contents) : contents;
+            return Array.isArray(transformed) ? transformed.join("\n") : transformed;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@open-xchange/vite-plugin-replace-pkg",
+    "version": "0.0.1",
+    "description": "Vite plugin replacing a specific external package with an arbitrary source code module",
+    "repository": {
+        "url": "https://gitlab.open-xchange.com/fspd/npm-packages/vite-plugin-replace-pkg"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": "18.18.0 || ^20.9.0 || >=21.1.0"
+    },
+    "packageManager": "yarn@4.4.0",
+    "type": "module",
+    "exports": "./dist/index.js",
+    "scripts": {
+        "prepare": "husky",
+        "prepack": "yarn build && yarn lint",
+        "build": "npx --yes rimraf dist && tsc",
+        "lint": "eslint ."
+    },
+    "lint-staged": {
+        "*.{js,ts,json}": "yarn lint"
+    },
+    "dependencies": {
+        "@open-xchange/vite-helper": "0.0.3"
+    },
+    "devDependencies": {
+        "@open-xchange/linter-presets": "0.4.2",
+        "@types/node": "22.1.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"
+    }
+}