Bundler capabilities (plugins)

This feature is a work in progress. Capabilities will be replaced by plugins in the future.

Capabilities allow customization of bundler options. Cloudpack provides some built-in capabilities, but you can also implement your own for extra config modifications.

For simple JSON-like overrides, you can also use bundlerOptions, but capabilities are required for any customization involving class instances, such as webpack plugins.

Configuration

Both built-in and custom capabilities are configured under PackageSettings.bundlerCapabilities in cloudpack.config.json.

interface BundlerCapabilityOptions {
  // true: enable the capability
  // object: enable the capability with these options
  // false: disable the capability
  [capabilityName: string]:
    | boolean
    | {
        /* capability options */
      }
}

Example:

{
  "$schema": "https://unpkg.com/@ms-cloudpack/cli/schema/AppConfig.json",
  "packageSettings": [
    {
      "match": "foo",
      "bundlerCapabilities": {
        "alias": {
          "bar": "baz",
        },
      },
    },
  ],
}

Built-in capabilities

Cloudpack provides some built-in capabilities.

Source: ori, rspack, webpack, or rollup.

alias

Remap an import path to another path.

Options: Record<string, string>

• key: original import string
• value: replacement

The behavior varies slightly between bundlers: see docs for ori (esbuild) alias, or rollup output.path, or the object syntax of webpack externals or rspack externals. (We don't use webpack/rspack resolve.alias here because it doesn't work for externalized dependencies.)

asset-inline

Handle the given file extensions as inline assets.

Options:

• extensions: string[] | Record<string, boolean> - extensions to inline

The extensions option can be specified in two formats:

• Array (e.g., ['avif', 'webp']): Use only these extensions, replacing the default list
• Object (e.g., { 'svg': false, 'avif': true }): Modify the default list by removing (false) or adding (true) extensions

Do not include the leading dot in extension names.

define

Replace identifiers at build time.

Options: Record<string, string> where each value is a JS literal string.

Example:

{
  "packageSettings": [
    {
      "match": "my-pkg",
      "bundlerCapabilities": {
        "define": {
          "process.env.NODE_ENV": "\"production\"",
          "__DEV__": "false",
        },
      },
    },
  ],
}

Note: Opt to use global define[./cloudpack-config#define] instead of this capability for global definitions. Link remote is a good candidate for this capability.

resolve-web-extensions

Enables React Native type resolution of .web.ts extensions.

Options: true to enable.

Custom capabilities

You can implement your own capabilities for custom config modifications, such as enabling GraphQL transforms.

Custom capabilities must be registered under bundlerCapabilitiesRegistry in cloudpack.config.json:

{
  "$schema": "https://unpkg.com/@ms-cloudpack/cli/schema/AppConfig.json",
  // This is a mapping from capability name to implementation file
  "bundlerCapabilitiesRegistry": {
    "demo": "./scripts/demoCapability.mjs",
  },
}

You can then enable, disable, or configure them for specific packages as shown under Configuration.

A custom capability file (./scripts/demoCapability.mjs in the example above) looks something like this. Using the BundlerCapability type will pull in the correct config types for all the bundlers.

// @ts-check
/**
 * @typedef {{ text?: string }} DemoOptions your options here
 * @type {import('@ms-cloudpack/cli').BundlerCapability<DemoOptions>}
 */
const capability = {
  name: 'demo',
  description: 'Demo of config customization with a capability.',
  // Each implementation can modify the config as needed (either mutate it or return a new object).
  // You don't need to include an implementation for every bundler.
  // `config` is the native bundler configuration object, and `options` is the custom capability options.
  implementations: {
    ori: (config, options) => {
      // Properties are mostly esbuild options (https://esbuild.github.io/api/#general-options)
      // with modifications as noted in the types.
      return config
    },
    rspack: (config, options) => {
      // https://rspack.dev/config/index
      return config
    },
    webpack: (config, options) => {
      // https://webpack.js.org/configuration/
      return config
    },
    rollup: (config, options) => {
      // https://rollupjs.org/configuration-options/
      return config
    },
  },
}
export default capability

You can see a complete example in Cloudpack's onedrive-mock app.