Transpile TypeScript modules for Dynamics 365 simply using rollup.js
Today we’re going to learn how to bring Dynamics form customisations to the modern era. No more files that are thousands of lines long, no more syntax errors, fewer bugs, and lower time to deploy.
The community is filling with useful ideas on how to utilise TypeScript for Dynamics customisations. You may have seen Scott Durow recently detailed how to get started with TypeScript, or Max Ewing’s post on how to create packages for Dynamics in TypeScript. This post focuses on similar core concepts, but uniquely expands on the focus of modules and build processes to modernise Dynamics customisations.
This post will begin with some assumptions (uh oh).
- You’re a Dynamics developer
- You’re using (or thinking of using) TypeScript for form customisations
- You’re using (or thinking of using) a modular design structure in your form scripts
If either of points 2 or 3 are false, I’d like to briefly try and convince you to consider them. (If both are true, you may want to skip the next two sections.)
Giving modular TypeScript a go
Dynamics developers are increasingly turning to TypeScript to write their form customisations in Dynamics. The reasons behind this are TypeScript’s benefits which, in a Dynamics context, can be summarised as:
In practice, this means intellisense against the Dynamics Client API; no more typos causing syntax errors at runtime! All that’s required is a simple import of @types/Xrm into your code (which I later explain).
Modular code design
As projects evolve and grow, Dynamics form scripts can become large, unstructured and difficult to maintain. This is especially prominent when following the pattern of providing just one script per form.
As an alternative, I’d like to suggest modules.
Good authors divide their books into chapters and sections; good programmers divide their programs into modules.
Like a book chapter, modules are just clusters of words (or code, as the case may be).
Good modules, however, are self-contained with distinct functionality, allowing them to be shuffled, removed, or added as necessary, without disrupting the system as a whole.
An example of modules in Dynamics
In this example, I demonstrate a requirement that gets the name of a lookup field value, and based on that value, toggles another field’s value.
The code to get a lookup’s name could be used elsewhere across different forms, so I’ve separated it into its own module called Common:
Common is then imported into the Contact script, and used in an onLoad function:
It’s important to note Contact is not a module, but a namespace. Its onLoad function doesn’t require an instantiated object and can be called directly from a Dynamics event handler.
If you’re following along, make sure to change your field schema names to fields that exist in your testing environment (mine are
"dc_umbrellarequired"), where the first is a lookup and the second is a boolean.
Rollup our example
That’s where rollup.js comes in. It’s going to give us the tools to create a build pipeline that:
- Transpiles our code
- Recursively look through our code for dependencies from a given entry point
- Optionally run plugins such as babel
- Bundles our code into one, Dynamics and browser-ready output file
And it’s really simple. Here’s how.
Step 1: Install rollup
In the code directory from the code sample above, run the following from the command line:
npm install --global rollup`
npm install --save-dev rollup-plugin-typescript
Step 2: Create a rollup config file
Rollup can be run manually through the CLI each time. But config files are too powerful and convenient to pass up! So, create rollup.config.js in your code’s root as follows:
input relative path is set to your contact script’s directory as necessary.
3. Run your rollup
From the command line, run the following command to build your code, and output it to the
rollup -c --experimentalCodeSplitting
And that’s it! Upload the output .js file (should be in your
/build/ directory) to Dynamics, add it to a Dynamics form and register the onLoad message as
This post has detailed how we can structure our modular code on small to enterprise Dynamics 365 projects to increase our script’s:
- There are many bundlers out there in the wild. This walkthrough uses rollup.js. Experiment with Webpack and Gulp to achieve the same results.
- Test your TypeScript files with Xrm tests. Here’s a recent post of mine detailing how Web API calls can be tested using xrm-mock and sinon.js.
- Add plugins to rollup.js. How about eslint to lint your code when it’s built, or uglify to minify your build output for production?