Key concepts and terminology

There are multiple environments to consider:

In addition the Test and Run environments can be further divided into:

All these environments support different features, and consequently also has differing limitations.

Typically a test environment is more limited than the run environment, and in order to write useful tests, some runtime features must be simulated.

When programming in Javascript there is always a global scope. Depending on which Javascript engine/environment you are in, the global scope is different.

There are currently few JavaScript engines capable of running TypeScript directly, so a build step must transpile your TypeScript to JavaScript before it can be deployed to Enonic XP. The build also targets a conservative language level, because XP’s default engine supports an older version of JavaScript.

For the execution model, the JavaScript engines XP ships, and the exact language level they support, see the Enonic Development Kit reference: Runtime and TypeScript.

A module is a way to structure your code into reusable, self-contained units that export functionality for other modules to import.

Enonic XP uses the CommonJS module format on the server, which is why you use require and exports in server-side code. TypeScript is authored as ECMAScript Modules (ESM), so the build transforms server files to CommonJS, while client-side assets are emitted as ESM for the browser.

In addition to the transpilation and transformation of separate TypeScript files, you may want to use code that other people have written. This code is typically distributed as npm packages. This is where bundling comes in.

Bundling is the process of combining all the code you need into a single file. Such a bundle is known as an entry point.

In a project you may want to have multiple entry points, each representing a different part of your application.

Bundlers are also smart enough to separate shared code into separate bundles, such bundles are known as chunks.

There are a bunch of transpilers, transformers🤖 and bundlers out there, each of them with their own strengths and weaknesses.

It has been difficult to find a single tool that supports all the required features. Each tool typically only solves a subset of the problem.

This is where meta-tools come in. Meta-tools are tools that combine multiple tools to solve a larger problem. For many years Webpack has been the most common tool for working with JavaScript code. It is very powerful and flexible, but also very complex and difficult to configure. In addition, it is not very fast.

tsdown is a simple and fast bundler specifically designed for TypeScript code. Powered by Rolldown (a Rust-based bundler built on the same oxc toolchain), it is easy to use and configure, and has all the features needed to work with both server- and client-side code in Enonic XP. Our setup uses tsdown as the meta-tool.

The fundamental concepts should now be established. Moving forward, let’s create a project and the build system.