@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

npm install --save-dev @imtf/profile-scripts

or

yarn add -D @imtf/profile-scripts

Usage

Start (development/watch mode)

profile-scripts start

Starts the build in watch mode and serves output at:

http://localhost:3010

Build (Production)

profile-scripts build

Generates the production bundle in the build/ directory.

CLI Options

--entryPoint

Specify a custom entry file.

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.

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).

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

module.exports = {
  name: "remote-app",
  exposes: {
    "./App": "./src/App",
  },
  filename: "remoteEntry.js",
  library: { type: "module" }, // **required**
};

Build Configuration

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:

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)

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.

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.