Deploying for Web

When run from the IDE, the Debugger takes care of putting all the pieces for your WebAssembly executable into place to run them in the browser. For actual deployment to your own servers, some additional thought is needed.

Essentially, there are at least three files generated by a WebAssembly project:

  • RemObjectsElements.js – this file is shared by all Elements WebAssembly modules, and contains glue code for the interaction between JavaScript and WebAssembly. While it is generated next to your executable as part of the build, it is a static file and is not affected by the contents of your project. If you deploy more than one WebAssembly module to the same page, you only need one copy of this file.
  • MyModule.js – this file is generated during build and contains project-specific APIs to let JavaScript code interact with the specific types and APIs your module exposes.
  • MyModule.wasm – this, finally, is the actual executable containing the code you wrote, compiled to WASM.

Depending on your project type and contents, additional files might be generated or copied to the output folder, such as resources.

These are in addition to one (or more) HTML pages and reated files that embed and use the WebAssembly module. The project templates create a dummy index.html for you that's mainly used for debugging and testing purposes. For a real-life deployment, this will be replaced by actual .html files or HTML generated server side by your hosting platform such as ASP.NET, PHP or the like, that already exist as part of your site.

Note that current browsers only execute WebAssembly code in files loaded via HTTP(S) from a remote server. You cannot use local files loaded via a file:/// URL to run WebAssembly. This is a restriction put in place by the browsers, and affects all WebAssembly, not just Elements.

To deploy the project as is, including the dummy index.html file, you will want to place the .html into a folder served by your webserver, and the generated files (from the Bin/Release/WebAssemnbly/wasm32 folder) into the wasm subfolder next to index.html:

./index.html
./wasm/RemObjectsElements.js
./wasm/MyModule.js
./wasm/MyModule.wasm

These paths are not a hard convention; they are simply the paths that the dummy index.html file uses to access the files. You can choose a different structure altogether, as long as you adjust the paths in your HTML to match. Within the wasm subfolder, you will want to maintain the folder structure generated from our project's output, for example for resources subfolders.

The important parts are that the two .js files are loaded via a <script tag, and the call to MyModule.instantiate("wasm/MyModule.wasm") (where MyModule is of course the actual name of your executable) to load and start up the WebAssembly module:

<script lang="javascript" src="wasm/RemObjectsElements.js"></script>
<script lang="javascript" src="wasm/MyModule.js"></script>

<script lang="javascript">
    MyModule.instantiate("wasm/MyModule.wasm").then(function (result) {
        console.log("WebAssembly file MyModule.wasm has been loaded.");
        var program = result.Program();
        program.HelloWorld();
    });
</script>

Also note that not all web servers will automatically serve all file types. In particular, IIS will not serve .wasm files by default, and instead return a 404 error code as if the file does not exist – potentially leading to a "Cannot load MyModule.wasm" error message.

To enable IIS to serve .wasm files open the "MIME Types" configuration panel in IKS admin and add an entry that maps ".wasm" to the "application/binary" MIME type.

The same might apply to other non-standard files that are part of your project, for example .dfm resource files when using Delphi VCL.

How Debugging Works

WebAssembly debugging is supported for Modules running in the browser.

When debugging WebAssembly for a web module, the IDE runs an embedded HTTP server that serves up the necessary files from your project. The root of the server is the folder containing your index.html file, and any files next to it or in subfolders.

The HTTP Server also serves the projects's output folder as a virtual sub-folder, under ./wasm. This way, the path relationship between the test .html file (and related files you might add such as images or stylesheets) and the compiler-generated files is in tact.

There are two Project Settings used to control this behavior:

  • <DebugIndexHtmlFile>Web\index.html</DebugIndexHtmlFile> – specifies test file. The path to the file (which usually is relative to the project, but may also be absolute) will determine the root folder for the HTTP server, while the filename itself will determine the URL to be opened in the browser on launch.

  • <DebugUrl>http://localhost:1234/</DebugUrl> – optionally, a full URL to a test server can be provided. If so, the debugger will not launch its own HTTP server, but assume a server is running at the given URL, and that you have set it up to properly serve the test HTML and the WebAssembly files.

See Also