Tsup Starter

You can check which version of Gradle wrapper your project is using by issuing this command:

You can upgrade your Gradle wrapper by issuing this command:

Read more about Upgrading the Gradle Wrapper.

We suggest to keep your project on the latest LTS version of Node, which can be found here.

The Tsup Starter uses the Gradle node plugin, which is defined like this:

and configured like this:

Any Gradle task that runs scripts in Node should depend on npmInstall:

Sometimes you want to run node scripts directly (not via Gradle). For example, to run Enonic XP in the [Watch mode].

In order to use the correct version of Node, use the following command:

It will use the version specified in the .nvmrc file:

Gradle does support incremental build, but using the continuous mode is NOT the most efficient option. Gradle can detect file changes, but it doesn’t know much about the dependency tree of JavaScript files, i.e. which other files need to be recompiled once a single JavaScript file is changed. Gradle will simply rebuild "everything" by calling:

Tsup/esbuild doesn’t support filesystem caching, like Webpack, but they do support watch mode.

This starter supports hot reload. Changes in your source code - both server-side and client-side - will be automatically rebuilt and displayed in the browser without you having to manually rebuild the app or reload the browser window.

Follow the steps below to enable this mode (we assume you are using Enonic CLI).

This will start the project’s sandbox in development mode and execute dev command which will watch for changes in the source-code and automatically rebuild the app.

Add an API library as a dependency to your build.gradle:

Jar file of an API library typically contains a CJS wrapper which is required at runtime.

The contents of the jar file are NOT available at compile time, so it cannot be bundled. Instead, we configure the transpiler to treat the library import path as an external (expecting it to exist at runtime).

You can use the following command to install a node module you want to use (for example, sha.js):

This will add sha.js under dependencies in the package.json file, and download and extract the package into node_modules folder of your project.

By default, Tsup starter bundles all imported modules EXCEPT dependencies and peerDependencies. Since sha.js (in the example above) is added as a dependency, it will NOT be bundled!

To fix that we have to list it under noExternal in the Tsup build config:

For server-side dependencies this is done in tsup/server.ts:

For client-side dependencies this is done either in tsup/client-static.ts (static client-side assets) or tsup/client-asset.ts ("standard" client-side assets):

For example, sha.js module expects buffer to exist in the global scope, but it does NOT exist in the Enonic XP JavaScript framework runtime environment.

We can use esbuild-plugin-polyfill-node to selectively polyfill only the parts of Node that is used by the node module:

Different JavaScript runtime environments have different properties on their Global object.

In addition, they even have different ways of accessing the Global object.

globalThis, introduced in ES2020 aims to consolidate the increasingly fragmented ways of accessing the Global object.

Some node modules support multiple runtime environments, and use the properties of the Global object to determine what runtime environment the code is running in.

To make matters worse, some of the polyfills themselves expect things to be a certain way.

For example, polyfilling of buffer only works if it can apply itself on the Global object. In the Enonic XP JavaScript framework, each controller runs in its own "sandbox" environment, so there really isn’t a Global object, there is rather a controller scope "local" object. In order for the buffer polyfill to work we can simply make globalThis point to the controller scope:

Sometimes all you need to polyfill is a single function rather than a whole API.

github.com/zloirock/core-js provides a bunch of such minimal "single function" polyfills.

Sometimes you need to replace environment variables in your code, for example, when you want to use different values in development and production environments, or when you want to use secrets or configuration which are not checked into source control.

In the starter there is an example of how to do this.

At compiletime we’re setting the BROWSER_SYNC_PORT environment variable to 3000:

Then in the code we’re using the BROWSER_SYNC_PORT environment variable via process.env:

In order to avoid loading the same code multiple times, shared code is split into chunk files, which are only loaded once, but can be used many times via require in the JavaScript controllers.

It’s sort of like all the shared code exists in the global scope and don’t need to be loaded.

When it comes to files autogenerated by a build system, for example chunk files, they also need their own "namespace".

In Tsup Starter we can "name space" its chunks like this:

There is an admin tool called "Sample Tool" included in the Starter, located in src/main/resources/admin/tools/tool. When a project based on this starter is deployed, you will see it inside the XP menu.

Click "Sample Tool" in the menu to open the tool.

What you see here is essentially a React app inside the Admin Tool. If you open browser console, you will see a log message there saying something like

We have also added an example of importing an external Node module called Day.js which allows you to easily handle date/time operations.

Both of these integrations (React and Day.js) can be found in src/main/resources/static/admin/App.tsx.

The starter includes examples for the following widget interfaces:

The Dashboard widget (titled "Sample dashboard widget") will be shown on the XP Dashboard page when you log in into Admin console.

Content Studio has a menu on the left-hand side and this widget’s icon will appear in this menu.

You’ll find this widget inside the Context Panel on the right hand side of Content Studio’s. This panel can be opened by clicking the burger icon under the XP menu icon.

Files in the static folder are not available via the Assets service. Instead, they are made available via the Static Assets Library.

In order to enable immutable urls, a content hash is added to the files names at compile time. The content hash is generated from the file content (and location) and only changes, if the content (or location) of the file changes. This means that the browser can cache the asset "forever", and every time it encounters the url, it can simply load the asset from the cache.

Whenever you change a file, it will have a new content hash and thus a new url. In order for the browser to load the new url, the html response from the server needs to provide the new url. This is made possible with a manifest file, which contains mapping of original assets with their current content hash.

There are many ways of serving the files from the static folder to the browser. The Starter contains helper functions for doing this (inside the /lib/urlHelper).

For assets inside a Site, we recommend using the getSiteUrl function.

For assets inside an Admin extension (a tool or a widget), we recommend using the getAdminUrl function.

For assets inside a Webapp, we recommend using the getWebappUrl function.

The starter includes a sample page component at `src/main/resources/site/pages/sample-page/'.

The starter includes a sample layout component at `src/main/resources/site/layouts/sample-layout/'.

The starter includes a sample part component at `src/main/resources/site/parts/sample-part/'.

The starter includes a sample response processors (that injects a header into response) at `src/main/resources/site/processors/sample-processor.ts'.

The starter includes a sample site mapping (declared in src/main/resources/site/site.xml) which maps assets inside src/main/resources/static/ folder with a controller at `src/main/resources/site/static.ts' which generates correct hash-based static path for each asset.