Skip to content

10 WebResources Project

RemyDuijkeren edited this page Nov 1, 2026 · 4 revisions

WebResources Project

flowline clone and flowline init scaffold a WebResources/ project alongside your Plugins/ project for your JavaScript or TypeScript source, images, and other web resources.

It has a minimal Rollup build. The dist/ folder it produces is what flowline push deploys. See 06-Push-WebResources for how push wires up form event handlers and dependencies.

You don't need a cloned solution to get one. flowline scaffold webresources writes the same project into any folder, offline. Use it to add web resources to a repo that never had them:

flowline scaffold webresources
cd WebResources && npm install && npm run build

In a repo with a solution file, the project is named after it and added to it, as clone would. In a folder without one, you get a generic WebResources.csproj and push its output standalone:

pac auth create --environment <url>          # if you haven't
flowline push webresources --path ./WebResources/dist --solution-name <solution> --env <url>

--output picks the folder to scaffold into; --name names the project folder and its .csproj. Full behaviour, including what it refuses to write over, in 04-Command-Reference#scaffold.


Project structure

WebResources/
├── 📂 src/
│   ├── 📂 modules/           ← shared code, imported by entry points
│   │   └── 📜 common.ts
│   ├── 📜 account.ts         ← entry point (one per form/ribbon)
│   └── 📜 contact.ts
├── 📂 public/                ← static files copied to dist/ unchanged
│   ├── 📂 images/            
│   └── 📜 *.html
├── 📂 dist/                  ← build output (gitignored) — synced by 'flowline push'
├── 📜 eslint.config.mjs      ← ESLint config
├── 📜 package.json           ← npm config, packages, run scripts
├── 📜 rollup.config.mjs      ← Rollup config
├── 📜 tsconfig.json          ← TypeScript config
└── 📜 <SolutionName>.WebResources.csproj  ← .NET project file that runs 'npm run build'

This structure is a starting point. Flowline only looks in dist/ to push the web resources, so you can change anything else. See Using a different build tool.

Folder and project name are yours to change. push finds the WebResources project through the solution file. If it can't tell two projects apart, it stops and asks.

Warning

Flowline can't tell a Power Apps Portals or Code Apps project from a WebResources project. Don't put one beside a WebResources project in the same solution.


Setup

Node.js must be installed. Run npm install once after cloning.


Building

npm run build

dotnet build runs npm run build too:

dotnet build

npm run build does two things in sequence:

  1. build:static copies public/ to dist/ unchanged (images, HTML)
  2. build:js runs Rollup, compiling every .ts/.js in src/ to an IIFE in dist/

flowline push webresources builds the project by calling dotnet build, then syncs dist/ to Dataverse.

If you already built and tested, flowline push webresources --no-build skips the build and pushes the existing dist/.

Push refuses to run when dist/ is missing or empty, since that would delete every web resource.


Writing scripts

Write scripts in TypeScript or plain JavaScript, or mix them. clone scaffolds one starter of each, src/example.ts and src/example-js.js. Rename whichever suits you and delete the other.

ES modules

Write each script as an ES module. Export every function you register as an event handler:

// src/account.ts
import { hide } from './modules/common'

export function onLoad(executionContext: Xrm.Events.EventContext): void {
    const formContext = executionContext.getFormContext();
    hide('fax', formContext);
    var myName = formatName(formContext.getAttribute('name')?.getValue() ?? '');
}

// not exported — only used internally
function formatName(name: string): string {
    return name.trim();
}

The same in plain JavaScript:

// src/account.js
import { hide } from './modules/common.js'

export function onLoad(executionContext) {
    const formContext = executionContext.getFormContext();
    hide('fax', formContext);
    var myName = formatName(formContext.getAttribute('name')?.getValue() ?? '');
}

// not exported — only used internally
function formatName(name) {
    return name.trim();
}

Register Account.onLoad as the event handler. Use auto-wiring form event handlers for that.

Entry points

Every .ts or .js file directly in src/ is treated as an entry point, and Rollup compiles it to a separate .js file in dist/:

src/account.ts          →  dist/account.js
src/account-ribbon.ts   →  dist/account-ribbon.js
src/contact.ts          →  dist/contact.js

Files in src/modules/ are shared code. They are imported by entry points but not compiled as standalone files.

Both the output filename and the IIFE global come from the entry point's stem, so two entry points may not share one: src/account.ts and src/account.js would both build to dist/account.js and overwrite each other.

Shared code

Put utilities in src/modules/. They are plain ES modules, so import and export normally:

// src/modules/common.ts
export function hide(field: string, formContext: Xrm.FormContext): void {
    formContext.getControl(field)?.setVisible(false);
}

IIFE output and Dataverse event handlers

Dataverse calls a handler off a global (Account.onLoad), so Rollup bundles each entry point into an IIFE that exposes its exports as a global named after the file, in PascalCase:

File Global name Dataverse event handler
account.ts Account Account.onLoad
account-ribbon.ts AccountRibbon AccountRibbon.onSave
contact.ts Contact Contact.onLoad

To add a namespace prefix (MyCompany.Account.onLoad), set namespacePrefix in rollup.config.mjs:

const namespacePrefix = 'MyCompany.'; // don't forget the trailing dot

TypeScript and linting

The template ships with strict TypeScript (strict: true, target ES2022) and @microsoft/eslint-plugin-power-apps, a Microsoft ESLint plugin that flags deprecated and unsupported Dataverse API usage. Violations print during build but don't block it. Set eslint({ throwOnError: true }) in rollup.config.mjs to fail the build instead.

If you write plain JavaScript and don't want TypeScript, remove @rollup/plugin-typescript and tsconfig.json and update rollup.config.mjs to drop the TypeScript plugin.


Static files

Place images, HTML, and other static assets in public/. They are copied to dist/ unchanged on every build, preserving the folder structure:

public/images/logo.png  →  dist/images/logo.png
public/help.html        →  dist/help.html

For plain JavaScript without modules, put your .js files in public/ and ignore src/.


Using a different build tool

Why the scaffold uses Rollup

Rollup is a good fit for Dataverse web resources for a few specific reasons:

  • Named IIFE global per entry point, auto-discovered. Matches exactly what Dataverse expects (Account.onLoad off a global). rollup.config.mjs scans src/ and turns each file into its own build — adding a new contact.ts file is picked up automatically, no config change. Vite can't do this for multiple entries — it's Rollup underneath, and Rollup itself refuses iife/umd output for more than one entry point. esbuild can do a named global, but only one per build call, so multiple files need the same manual looping this config already does.
  • Minimal config. No dev server or HMR needed — you test inside a live Dataverse form, not a previewed page, so that machinery would be dead weight.

Swapping the build tool

You can replace Rollup with any tool: Vite, esbuild, Webpack, or plain tsc. The only contract is that npm run build fills dist/ with the files to deploy.

To switch:

  1. Replace rollup.config.mjs and update devDependencies in package.json with your preferred tool.
  2. Update the build:js script in package.json to call your tool instead of rollup --config.
  3. Ensure your tool outputs IIFE bundles to dist/ with PascalCase global names, or adjust your Dataverse event handler registrations to match whatever output format you choose.

The build:static script (copies public/ to dist/) is independent and can stay as-is or be folded into your build tool's config.

Clone this wiki locally