TREX

TREX is TRES internet's internal build- and development tool for design system projects. Since v8 it is powered by Vite.

Migrating from v7? See MIGRATION-v8.md. For the smoothest migration, open GitHub Copilot in plan mode and add both README.md and MIGRATION-v8.md as context. Copilot will then generate a step-by-step migration plan tailored to your project.

Installation

pnpm i @tresinternet/trex

Quick start

Create a trex.paths.js with your project paths and two Vite config files.

trex.paths.js

export const paths = {
    outDir: '../MyProject.Website/wwwroot/dist',
    styles: {
        entries: {
            'style':   'src/stylesheets/style.scss',
            'library': 'src/stylesheets/library.scss',
            'print':   'src/stylesheets/print.scss',
        },
        loadPaths: ['src/stylesheets', 'node_modules'],
    },
    scripts: { entriesGlob: 'src/scripts/*.{js,ts}' },
    html: {
        templatesDir: 'src/html',
        iconsDir:     'src/assets/icons',
        mailtemplatesDir: 'src/html/9_mailtemplates',
    },
    assets: { src: 'src/assets', stripBase: 1, fontsDir: 'src/assets/fonts', iconsSrc: 'src/assets/icons' },
    notminified: {
        entry:  'src/stylesheets/rte_styles.scss',
        output: '../MyProject.Website/wwwroot/css',
    },
    server: { port: 3000 },
};

vite.config.js — design system dev server + full build

import { createTrexViteConfig } from '@tresinternet/trex';
import { paths } from './trex.paths.js';

export default createTrexViteConfig(import.meta.dirname, paths, {
    njkData: { client: 'My Project' },
});

vite.watch.config.js — write CSS/JS to wwwroot on every save (for Umbraco development)

import { createTrexWatchConfig } from '@tresinternet/trex';
import { paths } from './trex.paths.js';

export default createTrexWatchConfig(import.meta.dirname, paths);

vite.rte.config.js — unminified RTE stylesheet

import { createTrexRteConfig } from '@tresinternet/trex';
import { paths } from './trex.paths.js';

export default createTrexRteConfig(import.meta.dirname, paths);

Config factories

createTrexViteConfig(root, paths, options?)

Full Vite config for the design system: HTML (Nunjucks + MJML), CSS, JS, static assets, image optimisation, WebP generation, and the Vite dev server with HMR.

export default createTrexViteConfig(import.meta.dirname, paths, {
    njkData: { client: 'My Project' },
});

createTrexDeployConfig(root, paths, options?)

Asset-only build for CI/CD deployment alongside Umbraco. Skips HTML, MJML, and the pincode file. emptyOutDir is false so existing HTML in wwwroot is untouched.

export default createTrexDeployConfig(import.meta.dirname, paths);

createTrexWatchConfig(root, paths, options?)

Runs Rollup in watch mode: rebuilds and writes CSS, JS, and assets to outDir on every source-file change. Intended to run alongside pnpm dev in a second terminal so Umbraco pages pick up style changes on page reload.

• HTML templates are skipped (Umbraco provides its own).
• emptyOutDir is false to avoid clearing wwwroot between rebuilds.

export default createTrexWatchConfig(import.meta.dirname, paths);

createTrexRteConfig(root, paths)

Builds the Rich Text Editor stylesheet without minification and writes it directly to the Umbraco wwwroot/css directory.

If paths.notminified is not set, this config now performs a no-op build and logs a warning instead of throwing. This keeps vite build --config vite.rte.config.js safe in projects that do not use a standalone RTE output.

export default createTrexRteConfig(import.meta.dirname, paths);

Recommended package.json scripts

{
    "scripts": {
        "dev":     "vite",
        "watch":   "vite build --config vite.watch.config.js",
        "serve":   "pnpm run dev & pnpm run watch",
        "build":   "vite build",
        "deploy":  "vite build --config vite.deploy.config.js",
        "rte":     "vite build --config vite.rte.config.js"
    }
}

| Script | Description | | -------- | ----------------------------------------------------------------- | | dev | Design system dev server with HMR (library viewer) | | watch | Write compiled CSS/JS to wwwroot on every source change | | serve | dev + watch simultaneously — use when developing with Umbraco | | build | Full production build: HTML, CSS, JS, assets (RTE auto-included) | | deploy | Asset-only build for CI/CD (RTE auto-included) | | rte | Build the unminified RTE stylesheet standalone |

CI/CD integration

Azure Pipelines

When using the TRES templates for design library builds in Azure Pipelines, ensure that the design-library-cj2.yml template is invoked with useVite: true:

stages:
  - stage: BuildDesignLibrary
    jobs:
      - job: BuildDesignLibrary
        displayName: Build Design Library
        workspace:
          clean: all
        variables:
          - group: tres-internet-devops-group
        steps:
          - template: templates/design-library/design-library-cj2.yml@templates
            parameters:
              ftpUsername: $(DESIGN_LIBRARY_FTP_USERNAME)
              ftpPassword: $(DESIGN_LIBRARY_FTP_PASSWORD)
              workingDir: ${{ variables.workingDir }}
              outputDir: ${{ variables.outputDir }}
              customerFolder: ${{ variables.customerFolder }}
              cleanDestination: true
              usePnpm: true
              useVite: true

Setting useVite: true ensures the pipeline uses the modern Vite-based build instead of the legacy Gulp toolchain, and triggers the correct scripts (build, deploy, rte) as defined in your package.json.

Path configuration (TrexPaths)

All paths are relative to the project root (import.meta.dirname) unless noted otherwise.

| Property | Type | Description | | --------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | outDir | string | Output directory for all built assets | | pin | string \| number | Written to dist/pincode.config after each build | | styles.entries | Record<string, string> | Named SCSS entry points: { 'style': 'src/stylesheets/style.scss' } | | styles.loadPaths | string[] | SCSS load paths for @use / @forward | | styles.layoutModificationsInput | string | SCSS directory scanned for Layout modification: comments | | scripts.entriesGlob | string | Glob for TS/JS entry files; each match becomes an output file | | html.templatesDir | string | Root directory for Nunjucks templates | | html.iconsDir | string | SVG icons directory; auto-injected as icons in Nunjucks context | | html.mailtemplatesDir | string | Directory of MJML mail templates | | assets.src | string | Source directory for static assets | | assets.stripBase | number | Path segments to strip when building the output path | | assets.fontsDir | string | Source directory for fonts (e.g. src/assets/fonts). Used by the dev-server redirect so url('../fonts/') in SCSS resolves correctly. Omit when fonts live in public/fonts/. | | assets.iconsSrc | string | SVG icons source (e.g. src/assets/icons). When placed inside assets.src, it is automatically excluded from the general assets copy to avoid duplication. | | assets.indexSrc | string | Source path for the root index.html redirect | | library.designSystemSrc | string | Source directory for the Design System dist (e.g. node_modules/@tresinternet/design-system/dist) | | library.designSystemStripBase | number | Path segments to strip from designSystemSrc when building the output path | | library.designSystemIgnore | string[] | Optional glob ignore patterns inside designSystemSrc (e.g. ['**/example/**']) | | library.jsonSrc | string | Path to library.json | | library.libraryDistDir | string | Design System dist dir, served under /library/ in the dev server | | notminified.entry | string | Optional: SCSS entry for the RTE stylesheet | | notminified.output | string | Optional: output directory for the RTE stylesheet | | server.port | number | Vite dev server port (default: 3000) |

Options (TrexViteOptions)

| Option | Type | Description | | ---------------- | ----------------------- | --------------------------------------------------------------------------- | | njkData | Record<string, any> | Extra data merged into the Nunjucks template context | | njkConfigure | (env) => void | Callback to configure the Nunjucks environment (add filters, globals, etc.) | | imageOptimizer | false \| object | Options for vite-plugin-image-optimizer; false disables it | | webp | false \| { quality? } | Options for WebP generation via sharp; false disables it | | postcss | { plugins } | Override the PostCSS plugin list | | vite | UserConfig | Extra Vite config deep-merged into the generated config |

TREX development

To work on TREX itself, edit the TypeScript source in src/ and build:

pnpm run build   # tsc

To test against a consuming project, use a file: dependency in the consumer's package.json:

"@tresinternet/trex": "file:/path/to/tres-internet-library-trex"

After changes to TREX, rebuild it (pnpm run build) — the consuming project picks up the new dist automatically.