@imtf/profile-scripts 2.0.0-beta.0 → 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,26 +7,13 @@ const args = process.argv.slice(2);
 const scriptIndex = args.findIndex((x) => x === "build" || x === "start");
 const script = scriptIndex === -1 ? args[0] : args[scriptIndex];
 
-const useVite = args.includes("--vite");
-const useViteFederation = args.includes("--federation");
-
-// federation automatically implies vite
-const useViteBuild = useVite || useViteFederation;
-
-// Remove internal routing flags before forwarding
-const cleanedArgs = args.filter(
-  (arg) => arg !== "--vite"
-);
-
-const scriptPath = useViteBuild
-  ? require.resolve("../scripts/viteBuild.mjs")
-  : require.resolve("../scripts/esbuild.mjs");
+const scriptPath = require.resolve("../scripts/viteBuild.mjs");
 
 switch (script) {
   case "start":
   case "build": {
-    const nodeArgs = scriptIndex > 0 ? cleanedArgs.slice(0, scriptIndex) : [];
-    const scriptArgs = cleanedArgs.slice(scriptIndex + 1);
+    const nodeArgs = scriptIndex > 0 ? args.slice(0, scriptIndex) : [];
+    const scriptArgs = args.slice(scriptIndex + 1);
 
     if (script === "start") {
       scriptArgs.push("--watch");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtf/profile-scripts",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.1",
   "description": "Default scripts to bundle & transpile imtf front-end plugins",
   "main": "index.js",
   "bin": {
@@ -12,28 +12,21 @@
     "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": {
     "@originjs/vite-plugin-federation": "^1.4.1",
-    "@svgr/core": "^8.1.0",
-    "@svgr/plugin-jsx": "^8.1.0",
-    "@svgr/plugin-svgo": "^8.1.0",
     "@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",
     "serve-handler": "^6.1.6",
     "vite": "^7.3.1",
     "vite-plugin-css-injected-by-js": "^4.0.1",
-    "vite-tsconfig-paths": "^6.1.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

@@ -1,9 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-return */
-/* eslint-disable @typescript-eslint/no-unsafe-member-access */
-/* eslint-disable @typescript-eslint/no-unsafe-argument */
-/* eslint-disable @typescript-eslint/no-unsafe-assignment */
-/* eslint-disable @typescript-eslint/no-unsafe-call */
-
 import http from "http";
 import fs from "node:fs";
 import path from "path";
@@ -18,6 +12,7 @@ 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";
 
@@ -31,9 +26,7 @@ const {
 const consumerRoot = process.cwd();
 const outDir = "build";
 
-const entryAbs = entryPoint
-  ? path.resolve(consumerRoot, entryPoint)
-  : path.resolve(consumerRoot, "src/index.js");
+const entryAbs = resolveEntryPoint(entryPoint);
 
 // Force JSX transform for .js files in src
 const jsxPreTransformPlugin = {
@@ -143,7 +136,6 @@ const vitePlugins = [
 // Inject Module Federation support when --federation flag is provided
 if (enableFederation) {
   const federationConfig = await resolveFederationConfig();
-
   vitePlugins.push(federation(federationConfig));
 }
 
@@ -154,12 +146,13 @@ if (enableFederation) {
 const viteConfig = {
   root: consumerRoot,
   plugins: vitePlugins,
-  logLevel: watch ? "error" : "info", // !!! Need to discuss
+  logLevel: watch ? "error" : "info",
   build: {
     outDir,
     emptyOutDir: true,
     target: "esnext",
     sourcemap: watch,
+    chunkSizeWarningLimit: 3000,
     rollupOptions: {
       input: entryAbs,
       external: [

package/scripts/vitePlugins/viteNotifierPlugin.mjs

@@ -1,25 +1,33 @@
+/**
+ * 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 count = 0;
+  let isFirstBuild = true;
+  let rebuildCount = 0;
 
   return {
     name: "notifier-plugin-vite",
 
-    buildStart() {
-      count = 0;
-    },
-
     buildEnd(error) {
       if (error) return;
 
-      if (count++ === 0) {
-        if (watch) {
-          console.log(`1st build: ${Date.now()}`);
-        } else {
-          console.log("Successfully built");
-        }
-      } else {
-        console.log(`Rebuilt: ${Date.now()}`);
+      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()}`);
     },
   };
 };

package/scripts/vitePlugins/viteSvgPlugin.mjs

@@ -1,3 +1,12 @@
+/**
+ * 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",

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;