@imtf/profile-scripts 1.5.3 → 2.0.0-beta.1

package/README.md

@@ -0,0 +1,275 @@
+# @imtf/profile-scripts (Vite + Module Federation)
+
+## Overview
+
+`profile-scripts` is a standardized build and development utility designed for Profile applications within the ICOS.
+
+It provides a **vite-based build** with optional **Module Federation integration**.
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev @imtf/profile-scripts
+```
+
+or
+
+```bash
+yarn add -D @imtf/profile-scripts
+```
+
+---
+
+## Usage
+
+### Start (development/watch mode)
+
+```bash
+profile-scripts start
+```
+
+Starts the build in watch mode and serves output at:
+
+```
+http://localhost:3010
+```
+
+---
+
+### Build (Production)
+
+```bash
+profile-scripts build
+```
+
+Generates the production bundle in the `build/` directory.
+
+---
+
+## CLI Options
+
+### `--entryPoint`
+
+Specify a custom entry file.
+
+```bash
+profile-scripts start --entryPoint src/index.ts
+```
+
+If not provided, the following files are checked (in order):
+
+```
+index.ts
+index.tsx
+index.js
+index.jsx
+src/index.ts
+src/index.tsx
+src/index.js
+src/index.jsx
+```
+
+---
+
+### `--federation`
+
+Enable Module Federation support.
+
+```bash
+profile-scripts start --federation
+```
+
+When enabled:
+- Loads configuration from `federation.config.js` or `federation.config.mjs` in project root
+- Integrates with `vite-plugin-federation`
+
+---
+
+### `--externalGlobal`
+
+Map external dependencies to global variables (optional).
+
+```bash
+profile-scripts build --externalGlobal=react/jsx-runtime=window.jsxRuntime
+```
+
+Use this when a dependency is provided globally by the host application and should not be bundled.
+
+---
+
+## Project Requirements
+
+Minimal structure:
+
+```
+project-root/
+  src/
+    index.tsx (or equivalent entry)
+  package.json
+```
+
+For Module Federation:
+
+```
+federation.config.js
+```
+
+---
+
+## Remote Application Requirements
+
+To enable Module Federation integration, the **remote application** must be configured as follows.
+
+### Module Federation Configuration
+
+```js
+module.exports = {
+  name: "remote-app",
+  exposes: {
+    "./App": "./src/App",
+  },
+  filename: "remoteEntry.js",
+  library: { type: "module" }, // **required**
+};
+```
+
+---
+
+### Build Configuration
+
+```js
+experiments: { outputModule: true },
+
+externalsType: "global",
+
+externals: {
+  react: "React",
+  "react-dom": "ReactDOM",
+};
+```
+
+### Notes
+
+* The `library.type = "module"` configuration is **mandatory** for compatibility with vite-based host applications
+* `outputModule: true` ensures the remote is emitted as an ES module
+* React dependencies must be externalised and provided by the host application
+
+---
+
+## SVG Handling
+
+Built-in SVG support:
+
+- Files inside `src/` → transformed into React components
+- Files inside `src/assets/` or outside `src/` → converted to base64 data URLs
+
+---
+
+## CSS Handling
+
+CSS is automatically injected into the JavaScript bundle.  
+No separate CSS files are generated.
+
+---
+
+## Output
+
+Build output:
+
+```
+build/
+  index.js
+```
+
+- Format: IIFE
+- Designed for integration into host applications
+
+---
+
+## Environment Variable
+
+### `IMTF_MINIFY_WEBAPP`
+
+Controls minification:
+
+```bash
+IMTF_MINIFY_WEBAPP=false profile-scripts build
+```
+
+- Default: minification enabled
+- Uses Vite default minifier
+
+---
+
+## Notes
+
+- vite is the default build system
+- Module Federation is enabled only via `--federation`
+- Entry point is optional but must resolve to a valid file
+- External globals should be used only when dependencies are provided by the host
+
+---
+## Profile Configuration
+Two supported approaches are available based on how the remote is resolved.
+
+---
+
+### Option 1: URL-based Remote (Static)
+
+```js
+export default {
+  name: "host-app",
+  remotes: {
+    remoteModule: {
+      externalType: "url",
+      external: "http://localhost:3021/remoteEntry.js",
+      from: "webpack",
+      format: "esm",
+    },
+  },
+};
+```
+
+---
+
+### Option 2: Promise-based Remote (Dynamic)
+
+Use this when the remote URL needs to be resolved dynamically at runtime.
+
+```js
+export default {
+  name: "host-app",
+  remotes: {
+    remoteapp: {
+      externalType: "promise",
+      external: "<<resolver function as string>>",
+      from: "webpack",
+      format: "esm",
+    },
+  },
+};
+```
+
+---
+
+## Troubleshooting
+
+### Entry point not found
+
+Ensure one of the supported entry files exists or pass `--entryPoint`.
+
+---
+
+### Federation configuration missing
+
+Ensure `federation.config.js` or `.mjs` exists when using `--federation`.
+
+---
+
+### Runtime dependency issues
+
+If a dependency is expected from the host, configure it using `--externalGlobal`.
+
+---

package/bin/profile-scripts.js

@@ -7,7 +7,7 @@ const args = process.argv.slice(2);
 const scriptIndex = args.findIndex((x) => x === "build" || x === "start");
 const script = scriptIndex === -1 ? args[0] : args[scriptIndex];
 
-const scriptPath = require.resolve(`../scripts/esbuild.mjs`);
+const scriptPath = require.resolve("../scripts/viteBuild.mjs");
 
 switch (script) {
   case "start":

package/changelog.md

@@ -2,6 +2,14 @@
 
 Here you can find a resume of all changes between versions.
 
+## 2.0.0
+
+### Breaking changes
+
+- ViteJS will now be used as the default bundler for development and production builds.
+  The previous version of the package used esbuild.
+  This change allows Module Federation to be supported.
+
 ## 1.5.0
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtf/profile-scripts",
-  "version": "1.5.3",
+  "version": "2.0.0-beta.1",
   "description": "Default scripts to bundle & transpile imtf front-end plugins",
   "main": "index.js",
   "bin": {
@@ -12,21 +12,23 @@
     "changelog.md"
   ],
   "scripts": {
-    "build": "NODE_ENV=production node scripts/esbuild.mjs --entryPoint=src/index.tsx",
-    "start": "node scripts/esbuild.mjs --entryPoint=src/index.tsx --watch"
+    "build": "NODE_ENV=production node scripts/viteBuild.mjs",
+    "start": "node scripts/viteBuild.mjs --watch"
   },
   "prettier": "@imtf/prettier-config",
   "license": "UNLICENSED",
   "private": false,
   "dependencies": {
-    "@svgr/core": "^8.1.0",
-    "@svgr/plugin-jsx": "^8.1.0",
-    "@svgr/plugin-svgo": "^8.1.0",
+    "@originjs/vite-plugin-federation": "^1.4.1",
+    "@vitejs/plugin-react": "^5.1.4",
     "esbuild": "^0.27.0",
-    "esbuild-css-modules-plugin": "^3.1.4",
-    "esbuild-plugin-external-global": "^1.0.1",
-    "esbuild-plugin-inline-css": "^0.0.1",
-    "http-server": "^14.1.1",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "serve-handler": "^6.1.6",
+    "vite": "^7.3.1",
+    "vite-plugin-css-injected-by-js": "^4.0.1",
+    "vite-tsconfig-paths": "^6.0.1"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5"
   }
 }

package/scripts/utils/resolveEntryPoint.mjs

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_ENTRYPOINTS = [
+  "src/index.ts",
+  "src/index.tsx",
+  "src/index.js",
+  "src/index.jsx",
+  "index.ts",
+  "index.tsx",
+  "index.js",
+  "index.jsx",
+];
+
+/**
+ * Resolves the application entry point.
+ * Uses the provided entryPoint, otherwise falls back to defaults.
+ * Throws a simple error if no valid entry file is found.
+ *
+ * @param {string} [entryPoint] - Entry point passed via CLI
+ * @returns {string} Absolute path to resolved entry file
+ */
+const resolveEntryPoint = (entryPoint) => {
+  const consumerRoot = process.cwd();
+
+  // Use CLI entryPoint if provided
+  if (entryPoint) {
+    const resolvedPath = path.isAbsolute(entryPoint)
+      ? entryPoint
+      : path.resolve(consumerRoot, entryPoint);
+
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`[profile-scripts] entryPoint not found: ${entryPoint}`);
+    }
+
+    return resolvedPath;
+  }
+
+  // Resolve from defaults
+  for (const candidate of DEFAULT_ENTRYPOINTS) {
+    const fullPath = path.resolve(consumerRoot, candidate);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+
+  throw new Error(`[profile-scripts] entryPoint not found`);
+};
+
+export default resolveEntryPoint;

package/scripts/viteBuild.mjs

@@ -0,0 +1,195 @@
+import http from "http";
+import fs from "node:fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+import federation from "@originjs/vite-plugin-federation";
+import react from "@vitejs/plugin-react";
+import { transform } from "esbuild";
+import minimist from "minimist";
+import handler from "serve-handler";
+import { build as viteBuild } from "vite";
+import cssInjectedByJsPlugin from "vite-plugin-css-injected-by-js";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+import resolveEntryPoint from "./utils/resolveEntryPoint.mjs";
+import notifierPlugin from "./vitePlugins/viteNotifierPlugin.mjs";
+import svgPlugin from "./vitePlugins/viteSvgPlugin.mjs";
+
+const {
+  watch,
+  entryPoint,
+  externalGlobal,
+  federation: enableFederation,
+} = minimist(process.argv.slice(2));
+
+const consumerRoot = process.cwd();
+const outDir = "build";
+
+const entryAbs = resolveEntryPoint(entryPoint);
+
+// Force JSX transform for .js files in src
+const jsxPreTransformPlugin = {
+  name: "jsx-pre-transform",
+  enforce: "pre",
+  async transform(code, id) {
+    if (id.endsWith(".js") && id.includes(path.resolve(consumerRoot, "src"))) {
+      const result = await transform(code, {
+        loader: "jsx",
+        jsx: "automatic",
+        target: "esnext",
+        sourcemap: !watch,
+      });
+
+      return {
+        code: result.code,
+        map: result.map || null,
+      };
+    }
+    return null;
+  },
+};
+
+// Custom plugin to resolve package.json imports from node_modules
+const packageJsonResolver = {
+  name: "package-json-resolver",
+  enforce: "pre",
+  resolveId(source) {
+    if (!source.endsWith("/package.json")) return null;
+
+    const pkgName = source.replace(/\/package\.json$/, "");
+
+    const resolvedPath = path.resolve(
+      consumerRoot,
+      "node_modules",
+      pkgName,
+      "package.json",
+    );
+
+    if (fs.existsSync(resolvedPath)) {
+      return resolvedPath;
+    }
+
+    return null;
+  },
+};
+
+// Parse external globals
+const externalGlobals = externalGlobal
+  ? (typeof externalGlobal === "string"
+      ? [externalGlobal]
+      : externalGlobal
+    ).reduce((acc, curr) => {
+      const [key, value] = curr.split("=");
+      acc[key] = value;
+      return acc;
+    }, {})
+  : {};
+
+// Dynamically resolve optional federation.config.(js|mjs) from consumer root
+const resolveFederationConfig = async () => {
+  if (!enableFederation) return {};
+
+  const candidates = ["federation.config.mjs", "federation.config.js"];
+
+  for (const file of candidates) {
+    const fullPath = path.resolve(consumerRoot, file);
+    if (fs.existsSync(fullPath)) {
+      const mod = await import(pathToFileURL(fullPath).href);
+      return mod.default ?? mod;
+    }
+  }
+
+  throw new Error(
+    "[profile-scripts] --federation requires federation.config.(js|mjs) in project root.",
+  );
+};
+
+// Vite plugins
+const vitePlugins = [
+  // Must run before other plugins: transforms JSX inside .js files
+  // so Vite's import analysis can parse them correctly
+  jsxPreTransformPlugin,
+
+  // Custom resolver for package.json imports
+  packageJsonResolver,
+
+  // React JSX transform + automatic runtime
+  react({
+    jsxRuntime: "automatic",
+    include: /\.(js|jsx|ts|tsx)$/,
+  }),
+
+  // Resolve tsconfig path aliases
+  tsconfigPaths(),
+
+  // Inject CSS into the bundle for library consumers without needing separate CSS files
+  cssInjectedByJsPlugin(),
+
+  // Handle SVG as React components or assets
+  svgPlugin(),
+
+  // Log build and rebuild status to console
+  notifierPlugin(Boolean(watch)),
+];
+
+// Inject Module Federation support when --federation flag is provided
+if (enableFederation) {
+  const federationConfig = await resolveFederationConfig();
+  vitePlugins.push(federation(federationConfig));
+}
+
+/**
+ * Vite build configuration
+ * @type {import('vite').UserConfig}
+ */
+const viteConfig = {
+  root: consumerRoot,
+  plugins: vitePlugins,
+  logLevel: watch ? "error" : "info",
+  build: {
+    outDir,
+    emptyOutDir: true,
+    target: "esnext",
+    sourcemap: watch,
+    chunkSizeWarningLimit: 3000,
+    rollupOptions: {
+      input: entryAbs,
+      external: [
+        "react",
+        "react-dom",
+        "react-router-dom",
+        "IMTFPlugins",
+        ...Object.keys(externalGlobals),
+      ],
+      output: {
+        entryFileNames: "index.js",
+        format: "iife",
+        inlineDynamicImports: false,
+        globals: {
+          react: "React",
+          "react-dom": "ReactDOM",
+          "react-router-dom": "reactRouterDom",
+          IMTFPlugins: "IMTFPlugins",
+          ...externalGlobals,
+        },
+      },
+    },
+    minify: watch ? false : process.env.IMTF_MINIFY_WEBAPP !== "false",
+    watch: watch ? {} : null,
+  },
+};
+
+// Run Vite build in either watch or build mode
+if (watch) {
+  await viteBuild(viteConfig);
+
+  http
+    .createServer((...params) => handler(...params, { public: outDir }))
+    .listen(3010, () => {
+      // eslint-disable-next-line no-console
+      console.log("Running at http://localhost:3010");
+    });
+} else {
+  await viteBuild(viteConfig);
+}

package/scripts/vitePlugins/viteNotifierPlugin.mjs

@@ -0,0 +1,35 @@
+/**
+ * Logs Vite build and rebuild status with rebuild count.
+ * Distinguishes initial build vs subsequent rebuilds in watch mode.
+ *
+ * @param {boolean} watch - Whether running in watch mode
+ * @returns {import('vite').Plugin}
+ */
+const viteNotifierPlugin = (watch) => {
+  let isFirstBuild = true;
+  let rebuildCount = 0;
+
+  return {
+    name: "notifier-plugin-vite",
+
+    buildEnd(error) {
+      if (error) return;
+
+      if (!watch) {
+        console.log("Successfully built");
+        return;
+      }
+
+      if (isFirstBuild) {
+        console.log(`1st build: ${Date.now()}`);
+        isFirstBuild = false;
+        return;
+      }
+
+      rebuildCount += 1;
+      console.log(`Rebuilt (${rebuildCount}): ${Date.now()}`);
+    },
+  };
+};
+
+export default viteNotifierPlugin;

package/scripts/vitePlugins/viteSvgPlugin.mjs

@@ -0,0 +1,56 @@
+/**
+ * Vite plugin to transform SVG imports based on project conventions.
+ *
+ * - SVGs outside `src/` or inside `src/assets/` are converted to base64 data URLs
+ * - SVGs inside `src/` are transformed into React components using SVGR
+ *
+ * @param {Object} [options] - SVGR configuration options
+ * @returns {import('vite').Plugin}
+ */
+const viteSvgPlugin = (options = {}) => {
+  return {
+    name: "vite-svgr-plugin",
+    enforce: "pre",
+    async transform(code, id) {
+      if (!id.endsWith(".svg")) {
+        return null;
+      }
+      const svgPath = id.split("?")[0].split("#")[0];
+
+      // Read file content
+      const svg = await fs.promises.readFile(svgPath, "utf8");
+
+      // Determine relative path
+      const relativePath = path.relative(process.cwd(), svgPath);
+
+      // This is an asset ==> dataurl
+      if (
+        !relativePath.startsWith("src/") ||
+        relativePath.startsWith("src/assets/")
+      ) {
+        const dataurl = `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+        return {
+          code: `export default ${JSON.stringify(dataurl)};`,
+          map: null
+        };
+      }
+
+      // Otherwise it's a react component
+      const contents = await transform(
+        svg,
+        {
+          plugins: ["@svgr/plugin-svgo", "@svgr/plugin-jsx"],
+          ...options
+        },
+        { filePath: svgPath }
+      );
+
+      return {
+        code: contents,
+        map: null
+      };
+    }
+  };
+}
+
+export default viteSvgPlugin;

package/scripts/esbuild.mjs

@@ -1,94 +0,0 @@
-import { build, context } from "esbuild";
-import esbuild from "esbuild-plugin-external-global";
-import InlineCSSPlugin from "esbuild-plugin-inline-css";
-import CssModulesPlugin from "esbuild-css-modules-plugin";
-import minimist from "minimist";
-import HttpServer from "http-server";
-
-// eslint-disable-next-line import/no-named-as-default-member
-const externalGlobalPlugin = esbuild.externalGlobalPlugin;
-
-import notifierPlugin from "./notifierPlugin.mjs";
-import svgPlugin from "./svgPlugin.mjs";
-
-const {
-  watch,
-  entryPoint,
-  externalGlobal,
-  outbase = "src",
-} = minimist(process.argv.slice(2));
-
-const externalGlobals = externalGlobal
-  ? (typeof externalGlobal === "string"
-      ? [externalGlobal]
-      : externalGlobal
-    ).reduce((acc, curr) => {
-      const [key, value] = curr.split("=");
-      acc[key] = value;
-      return acc;
-    }, {})
-  : {};
-
-const entryPoints = entryPoint
-  ? typeof entryPoint === "string"
-    ? [entryPoint]
-    : entryPoint
-  : ["src/index.js"];
-
-/**
- * @type {import('esbuild').BuildOptions}
- */
-const config = {
-  entryPoints,
-  outbase,
-  outdir: "build",
-  platform: "browser",
-  bundle: true,
-  target: "es2024",
-  metafile: true,
-
-  sourcemap: watch ? "linked" : "external",
-
-  minify: watch === true ? false : process.env.IMTF_MINIFY_WEBAPP !== "false",
-
-  loader: {
-    // Enable JSX in .js files too
-    ".js": "jsx",
-    // Embed fonts
-    ".eot": "dataurl",
-    ".ttf": "dataurl",
-    ".woff": "dataurl",
-    ".woff2": "dataurl",
-    // Embed images
-    ".gif": "dataurl",
-    ".jpg": "dataurl",
-    ".png": "dataurl",
-  },
-
-  plugins: [
-    CssModulesPlugin({ inject: true }),
-    InlineCSSPlugin(),
-    svgPlugin(),
-    externalGlobalPlugin({
-      react: "window.React",
-      "react-dom": "window.ReactDOM",
-      "react-router-dom": "window.reactRouterDom",
-      IMTFPlugins: "window.IMTFPlugins",
-      ...externalGlobals,
-    }),
-    notifierPlugin(watch),
-  ],
-};
-
-if (watch) {
-  const ctx = await context(config);
-
-  // Enable watch mode
-  await ctx.watch();
-
-  // Create a server for the build directory
-  const server = HttpServer.createServer({ root: "build" });
-  server.listen(3010, () => console.log("Running at http://localhost:3010"));
-} else {
-  await build(config);
-}

package/scripts/notifierPlugin.mjs

@@ -1,24 +0,0 @@
-const notifierPlugin = (watch) => ({
-  name: "svgr",
-  setup(build) {
-    let count = 0;
-
-    build.onEnd((result) => {
-      if (result.errors.length > 0) {
-        return;
-      }
-
-      if (count++ === 0) {
-        if(watch) {
-          console.log(`1st build: ${new Date().getTime()}`);
-        } else {
-          console.log(`Successfully built`);
-        }
-      } else {
-        console.log(`Rebuilt: ${new Date().getTime()}`);
-      }
-    });
-  },
-});
-
-export default notifierPlugin;

package/scripts/svgPlugin.mjs

@@ -1,44 +0,0 @@
-import { transform } from "@svgr/core";
-import fs from "fs";
-import path from "path";
-
-const svgPlugin = (options = {}) => ({
-  name: "svgr",
-  setup(build) {
-    build.onLoad({ filter: /\.svg$/ }, async (args) => {
-      // Read file content
-      const svg = await fs.promises.readFile(args.path, "utf8");
-
-      // Determine relative path
-      const relativePath = path.relative(process.cwd(), args.path);
-
-      // This is an asset ==> dataurl
-      if (
-        !relativePath.startsWith("src/") ||
-        relativePath.startsWith("src/assets/")
-      ) {
-        return {
-          contents: svg,
-          loader: "dataurl",
-        };
-      }
-
-      // Otherwise it's a react component
-      const contents = await transform(
-        svg,
-        {
-          plugins: ["@svgr/plugin-svgo", "@svgr/plugin-jsx"],
-          ...options,
-        },
-        { filePath: args.path }
-      );
-
-      return {
-        contents,
-        loader: "jsx",
-      };
-    });
-  },
-});
-
-export default svgPlugin;