Vite plugin for the Mercury Design System

The @genexus/vite-plugin-mercury package serves the same purpose as the Mercury CLI (@genexus/mercury-cli package), allows to build and use the Mercury Design System.

Usage example in the vite.config.ts file:

import { mercury } from "@genexus/vite-plugin-mercury";
import { defineConfig, type PluginOption } from "vite";

export default defineConfig({
  plugins: [
    mercury({
      // Options...
    }) as PluginOption,
  ],
});

⚙️ Options

The vite-plugin-mercury accepts an options object of type MercuryOptions to customize its behavior:

export type MercuryOptions = {
  /**
   * An object to customize the location of the Mercury assets (CSS, font, and
   * icon files) in the distribution build.
   *
   * In dev mode these files are proxied to the real source.
   */
  assetsPaths?: MercuryOptionsAssets;

  /**
   * Customize which files are not hashed.
   *
   * **IMPORTANT!**: Use this field if you know what you are doing. Not hashing
   * the CSS files could lead to cache issues when changing the version of
   * Mercury.
   *
   * By default, all CSS bundle files are hashed to avoid any cache issue.
   */
  avoidHash?: {
    [key in
      | MercuryBundleBase
      | MercuryBundleReset
      | MercuryBundleOptimized]?: boolean;
  };

  /**
   * Determine which CSS files will be inserted at the end of html `head` as a
   * `style` tag. In some cases, this may improve initial load performance; for
   * example, inlining the `base/base` bundle.
   *
   * **Warning**: Abusing of this setting could lead to diminishing returns.
   *
   * Due to the previous point, this setting does not allow inlining the
   * `base/icons` CSS bundle, as it is a relatively big file that could bloat the
   * initial HTML size.
   *
   * By default, the `base/base` and `resets/box-sizing` CSS bundles are inlined.
   */
  cssInline?: {
    [key in
      | Exclude<MercuryBundleBase, "base/icons">
      | MercuryBundleReset
      | MercuryBundleOptimized]?: boolean;
  };

  /**
   * Determine which CSS files will be preloaded as a `<link>` tag.
   * In some cases, this may improve initial load performance.
   *
   * When using `true` the default config will be `{ position: "head", fetchPriority: "auto" }`
   *
   * **Warning**: Abusing of this setting could lead to diminishing returns.
   *
   * By default, the `"base/icons"` CSS bundle is preloaded at the `"body-end"`
   * position with `fetchPriority: "low"`.
   */
  cssPreload?: {
    [key in
      | MercuryBundleBase
      | MercuryBundleReset
      | MercuryBundleOptimized]?: MercuryOptionsAssetPreload;
  };

  /**
   * Allows overriding specific design tokens used by Mercury.
   *
   * All tokens can be overridden (primitives and semantics), but it's
   * recommended to only override those that are necessary to achieve the
   * desired customization.
   */
  overrides?: {
    tokens?: MercuryTokensDefinition;
  };

  /**
   * The theme variant in which Mercury is implemented.
   *
   * @default "mercury"
   */
  theme?: "mercury" | "globant";
};

export type MercuryOptionsAssets = {
  /**
   * Path where the CSS files of Mercury are located in the distribution build.
   *
   * @default "/assets/css/"
   */
  cssPath?: string;

  /**
   * Path where the font files of Mercury are located in the distribution build.
   *
   * @default "/assets/fonts/"
   */
  fontsPath?: string;

  /**
   * Path where the icon files of Mercury are located in the distribution build.
   *
   * @default "/assets/icons/"
   */
  iconsPath?: string;
};

export type MercuryOptionsAssetPreload =
  | boolean
  | {
      /**
       * The position where the link is placed.
       * - `"head"`: Places the `<link>` at the end of the html `head`.
       * - `"body-start"`: Places the `<link>` at the start of the html `body`.
       * - `"body-end"`: Places the `<link>` at the end of the html `body`.
       *
       * @default "head"
       */
      position?: "head" | "body-start" | "body-end";

      /**
       * Represents a hint to the browser indicating how it should prioritize
       * fetching a particular resource relative to other resources of the same
       * type.
       *
       * Based on [fetchPriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/fetchPriority).
       *
       * @default "auto"
       */
      fetchPriority?: "auto" | "high" | "low";
    };