Library: @onecx/build-utils

Overview

The @onecx/build-utils library provides a set of utilities for OneCX applications. It includes helper functions for build tasks, Module Federation library sharing, and other Node.js-related tasks.

Install the library in your project using npm as dev dependency:

npm install @onecx/build-utils --save-dev

Shared Library Configuration

The getOneCXSharedLibraryConfig function generates module federation shared library configuration for all dependencies, including subpackages. This function supports different module federation technologies and provides OneCX-specific recommendations for optimal sharing.

getOneCXSharedLibraryConfig(
  dependencies: Record<string, string>,
  shouldGenerateSubDeps: boolean,
  options?: SharedLibraryConfigOptions
): Record<string, SharedLibraryConfig>

Usage Example

@angular-architects/module-federation

For projects using @angular-architects/module-federation, set shouldGenerateSubDeps to false. The share() function automatically handles subpackages when includeSecondaries: true is set through the configCallback.

Example: Angular Architects Module Federation Configuration
const { getOneCXSharedLibraryConfig } = require('@onecx/build-utils');
const { withModuleFederationPlugin, share } = require('@angular-architects/module-federation/webpack');
const packageJson = require('./package.json');

function customConfigCallback(packageName, currentConfig) {
  // Override config for @angular-architects/module-federation
  currentConfig.includeSecondaries = true;
  currentConfig.requiredVersion = 'auto';
  return currentConfig;
}

const sharedEntries = getOneCXSharedLibraryConfig(
  packageJson.dependencies,
  false,  // Don't generate subpackages - handled by share()
  { configCallback: customConfigCallback }
);

const config = withModuleFederationPlugin({
  name: 'onecx-test-project-ui',
  filename: 'remoteEntryOneCX.js',
  exposes: {
    './OneCXTestModule': './src/main.ts'
  },
  shared: share(sharedEntries)
});

module.exports = config;

@module-federation/enhanced

For projects using @module-federation/enhanced, set shouldGenerateSubDeps to true to include all exported subpackages in the shared configuration.

Example: Module Federation Enhanced Configuration
const { getOneCXSharedLibraryConfig } = require('@onecx/build-utils');
const { withModuleFederationEnhancedPlugin } = require('@module-federation/enhanced/webpack');
const packageJson = require('./package.json');

const sharedEntries = getOneCXSharedLibraryConfig(
  packageJson.dependencies,
  true
);

const config = withModuleFederationEnhancedPlugin({
  name: 'onecx-test-project-ui',
  filename: 'remoteEntry.js',
  exposes: {
    './Module': './src/app/remote.module.ts'
  },
  shared: sharedEntries,
});

module.exports = config;

@nx/angular:module-federation

For NX workspaces using @nx/module-federation, set shouldGenerateSubDeps to true to include all exported subpackages in the shared configuration and add the generated shared entries to the additionalShared property of the ModuleFederationConfig object.

Example: NX Module Federation Configuration
import { ModuleFederationConfig, SharedLibraryConfig } from '@nx/module-federation'
import { getOneCXSharedLibraryConfig, getOneCXSharedRecommendations } from '@onecx/build-utils'

import * as pkg from 'package.json'

const sharedEntriesObject = getOneCXSharedLibraryConfig(pkg.dependencies, true)

// Reduce to array with object entries with libraryName and sharedConfig properties
const sharedEntries = Object.entries(sharedEntriesObject).map(([libraryName, sharedConfig]) => ({
  libraryName,
  sharedConfig
}))

const config: ModuleFederationConfig = {
  name: 'onecx-test-project-ui',
  filename: 'remoteEntry.js',
  exposes: {
    './Module': './src/app/remote.module.ts'
  },
  shared: (libraryName, sharedConfig) => {
    const config = getOneCXSharedRecommendations(libraryName, sharedConfig)
    // Add custom shared configurations to the config object if needed
    return config
  },
  additionalShared: sharedEntries // This will add the additional shared dependencies generated from package.json to the module federation config
}

export default config

Customization Options

Custom Configuration Callback

Modify the configuration properties for packages:

function customConfigCallback(packageName, currentConfig) {
  // Make all packages singletons
  currentConfig.singleton = true;

  // Set strict version for specific packages
  if (packageName === '@angular/core') {
    currentConfig.strictVersion = true;
  }

  return currentConfig;
}

const sharedEntries = getOneCXSharedLibraryConfig(
  dependencies,
  true,
  { configCallback: customConfigCallback }
);

Custom Package Filter

Exclude specific packages from being shared:

const { onecxPackageFilter } = require('@onecx/build-utils');

function customPackageFilter(packageName) {
  // Exclude internal packages
  if (packageName.startsWith('@internal/')) {
    return true;  // true = exclude
  }

  // Use default OneCX filter for other packages
  return onecxPackageFilter(packageName);
}

const sharedEntries = getOneCXSharedLibraryConfig(
  dependencies,
  true,
  { packageFilterCallback: customPackageFilter }
);

OneCX Shared Recommendations

The getOneCXSharedRecommendations function provides OneCX-specific recommendations for shared library configurations. It automatically applies optimized settings for Angular, OneCX, RxJS, PrimeNG, ngx-translate, and ngrx packages.

getOneCXSharedRecommendations(
  libraryName: string,
  sharedConfig: SharedLibraryConfig
): false | SharedLibraryConfig

Usage Example

import { getOneCXSharedRecommendations } from '@onecx/build-utils';

const sharedConfig = {
  singleton: false,
  strictVersion: false,
  eager: false,
  requiredVersion: 'any',
  shareScope: 'angular_21'
};

const recommendedConfig = getOneCXSharedRecommendations('@angular/core', sharedConfig);
// Output: { singleton: false, strictVersion: false, eager: false, version: '1.0.0', requiredVersion: 'any', shareScope: 'angular_21' }

Config Properties

The SharedLibraryConfig object can include the following properties:

Property Type Description

singleton

boolean

Whether only one instance should exist

strictVersion

boolean

Whether version mismatches should cause errors

eager

boolean

Whether to load immediately vs lazy

requiredVersion

string | false

Required version or any/false for no requirement

version

string

Actual version of the package

includeSecondaries

boolean

Include secondary entry points (for @angular-architects)

shareScope

string

Scope for sharing (e.g., angular_21)

For recommended libraries, the function applies the following defaults:

  • singleton: false — Allows multiple versions to coexist

  • strictVersion: false — Permits version flexibility

  • eager: false — Enables lazy loading of shared modules