[2025-11-10] Design Systems

Mercury v0.36.0

• The Mercury implementation is divided into the @genexus/mercury-build and @genexus/mercury-cli packages. Additionally, the @genexus/vite-plugin-mercury package has been added to facilitate configuration in Vite-based environments by @ncamera in #646

Important changes

• The CLI implementation for mercury has been moved to the @genexus/mercury-cli package (which uses the @genexus/mercury-build under the hood).

• The @genexus/mercury package now only contains the core implementation for Mercury (CSS, fonts, icons, and some JavaScript).

• Now, when running the mercury command of the CLI, the icons and fonts are generated under the node_modules/.genexus/mercury/assets/ folder. In other words, the mercury command generated the following content:

  • node_modules/.genexus/mercury/assets/css --> contains the CSS bundles to use in the dev server and dist build.
  • node_modules/.genexus/mercury/assets/fonts --> contains the fonts to use in the dev server and dist build.
  • node_modules/.genexus/mercury/assets/icons --> contains the icons to use in the dev server and dist build.

Tip

This change helps monorepo user experience fewer conflicts when multiple packages use different versions of Mercury, because now the Mercury assets will always be in the same folder (node_modules/.genexus/mercury/assets), regardless of the Mercury versions used in the monorepo.

• Added the @genexus/vite-plugin-mercury package to facilitate configuration in Vite-based environments. This package contains a Vite plugin which:

  • Removes the need to copy the Mercury assets for the dev server and dist build. You can safely delete all copy tasks for the Mercury assets.

    // vite.config.ts
    import { defineConfig } from "vite";
    import { mercury } from "@genexus/vite-plugin-mercury";
    
    // https://vite.dev/config/
    export default defineConfig({
      plugins: [
    -   viteStaticCopy({
    -     targets: [
    -       {
    -         src: "{{ CSS outDir path }}",
    -         dest: "{{ CSS bundles final path }}"
    -       },
    -       {
    -         src: "<path to node_modules>/@genexus/mercury/dist/assets/fonts",
    -         dest: "{{ Fonts final path }}"
    -       },
    -       {
    -         src: "<path to node_modules>/@genexus/mercury/dist/assets/icons",
    -         dest: "{{ Icons final path }}"
    -       }
    -     ]
    -   })
    +   mercury({
    +     // (Optional)
    +     assetsPaths: {
    +       // Path where the CSS files of Mercury are located in the distribution build.
    +       cssPath: "{{ CSS bundles final path }}", // Defaults to "/assets/css/"
    +
    +       // Path where the font files of Mercury are located in the distribution build.
    +       fontsPath: "{{ Fonts final path }}", // Defaults to "/assets/fonts/"
    +
    +       // Path where the icon files of Mercury are located in the distribution build.
    +       iconsPath: "{{ Icons final path }}" // Defaults to "/assets/icons/"
    +     },
    +
    +     // More options...
    +   })
      ]
    });

  • The base/base.css bundle in now automatically inlined in the index.html, so you don't need to load it.

  • The base/icons.css bundle in now preloaded in the index.html, so you don't need to load it.

  • The bundle hashes are now automatically applied in the index.html, so you can safely remove the following:

    - import { setBundleMapping } from "@genexus/mercury/bundles.js";
    - import { bundleToHashMappings } from "./assets/mercury-css/bundle-to-hash-mappings";
    
    - // Establishes the mapping between bundle names and their generated hashes.
    - // For example, it maps the `components/button` bundle name to `button-e261832acea09e81.css`
    - setBundleMapping(bundleToHashMappings);

• The installation guide for Angular, NextJS, React, and StencilJS has been simplified.

⚠️ Breaking changes

• Now, the CLI is no longer included when installing @genexus/mercury. You must install the @genexus/mercury-cli package to use the Mercury CLI.

• The CLI's outDir flag has been removed. Now, the generated CSS bundles will always be located in the node_modules/.genexus/mercury/assets/css folder.

• Changed the following default paths when using the Mercury CLI:

  	Before	After
  Fonts	"./assets/fonts/"	"/assets/fonts/"
  Icons	"./assets/icons/"	"/assets/icons/"

• Removed the alternative way ("Using already generated CSS bundles") of using the CSS from the docs, as this unwanted feature limited the possibilities of the build process and the CLI.

• The bundle-to-hash-mappings.ts file is now located in the ./node_modules/.genexus/mercury/bundle-to-hash-mappings.ts path.

Full Changelog: v0.0.228...v0.0.230