Upgrading projects from classic scripts to modules

When Construct's JavaScript coding feature was launched in 2019, all the scripts in a project ran as classic mode scripts. This is how JavaScript has run in web pages since its introduction in the 1990s. However modern JavaScript now uses modules - a newer and better way to organise scripts and their dependencies.

Construct 3 r226 added support for using modules for your project's JavaScript code. In Construct 3 r251, support for the legacy classic mode was removed. This tutorial will guide you through what's changed and how to update your code, in case you have any old projects still using classic mode.

Classic mode vs. modules

In classic mode:

• All your project's script files are loaded automatically on startup.
• You can't control the order script files are loaded in.
• Global variables and functions can be used everywhere, including in other scripts, and in scripts in event blocks.

In module mode:

• Only the project main script is loaded automatically on startup.
• Other script files aren't used unless you import them.
• You can control the order script files are loaded by the order you import them.
• Each module has its own scope. This means top-level variables and functions cannot be used outside the module, unless:
  • they are exported, and imported where they are used (recommended)
  • they are explicitly made global by adding them as properties on the global object (not recommended)

Using modules helps you organise your code better. For example, making all your variables and functions global is generally regarded as poor design, is prone to problems like naming clashes, and makes re-using code more difficult. Modules allow you to write clean, self-contained pieces of code that have clearly defined dependencies, and export a clearly defined interface for other code to use. Individual modules can then easily be re-used in different places.

You can learn more about how modules work in JavaScript at the MDN guide on JavaScript modules.

Changing modes

In Project Properties inside the Advanced section is a Scripts type setting. You can use this to change between Classic and Module modes. You should switch your project to use Modules mode. This affects how script files in your project are loaded, and you may have to make changes, as explained in the following steps.

Changing modes only affects script files. If you only use scripts in event blocks and don't have any script files at all, you don't need to do anything. Construct will automatically switch your project to use modules and everything will continue working as it did before.

Step 1: assign a main script

Once you've switched to modules mode, the first thing you need to do is tell Construct which is your main script. This is the only script that will be loaded on startup. All other scripts then need to be imported by this script.

Find the script you want to use as your main script in the Project Bar. Usually this is the script which has a call to runOnStartup. Select the script in the Project Bar, and some properties appear in the Properties Bar for it. Change the Purpose property to Main script. The main script also appears bold in the Project Bar.

Step 2: add exports

Next, for every other script file your project uses, look through it and identify which functions, classes and objects need to be made available to other script files. These need to be exported using the export keyword.

For example consider a JavaScript file utilities.js that defines a function add:

// utilities.js
function add(a, b)
{
	return a + b;
}

// utilities.js
export function add(a, b)
{
	return a + b;
}

// main.js
console.log(add(2, 3));

// main.js
import * as Utils from "./utilities.js";

console.log(Utils.add(2, 3));

// importsForEvents.js
import * as Utils from "./utilities.js";

export let myGlobalVariable = 0;

// globals.js
const Globals = {
	myGlobalVariable: 0,
	myOtherGlobal: 1,

	// Example global function
	someGlobalFunction()
	{
		/* ... */
	}
};

export default Globals;

// main.js
import Globals from "./globals.js";

// Change a global variable
Globals.myGlobalVariable = 1;

globalThis.myGlobalScopeVariable = 0;
globalThis.myGlobalScopeFunction = function ()
{
	/* ... */
}

// importsForEvents.js
import * as Main from "./main.js";