Integrating with JavaScript

This guide explains how to integrate JavaScript into your Utopia application.

Using Import Maps

Import maps provide a modern way to manage JavaScript module dependencies. Utopia includes built-in support for import maps through the class Utopia::ImportMap class.

Installing JavaScript Libraries

First, install the library using npm:

$ npm install jquery

Copy the distribution files to public/_components:

$ bundle exec bake utopia:node:update

This will copy the library's distribution files (typically from node_modules/*/dist/) to your public/_components/ directory, making them available for local serving.

Creating the Import Map

Create a global import map in lib/my_website/import_map.rb:

require "utopia/import_map"

module MyWebsite
	IMPORT_MAP = Utopia::ImportMap.build(base: "/_components/") do |map|
		map.import("jquery", "./jquery/jquery.js")
	end
end

Then load this in lib/my_website.rb:

require_relative "my_website/import_map"

Adding to Your Pages

Add it to your page template (pages/_page.xnode), using relative_to to adjust paths for the current page:

<html>
	<head>
		#{MyWebsite::IMPORT_MAP.relative_to(request.path + "/")}
	</head>
	<body>
		<!-- Your content -->
	</body>
</html>

Using the Library

Once the import map is set up, you can import and use the library in your scripts:

<script type="module">
	// <![CDATA[
	import $ from 'jquery';
	
	$(document).ready(function() {
		console.log("jQuery is ready!");
	});
	// ]]>
</script>

Advanced Import Map Features

Using CDN URLs

Import maps support direct CDN imports without downloading files:

IMPORT_MAP = Utopia::ImportMap.build do |map|
	map.import("react", "https://esm.sh/react@18")
	map.import("vue", "https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.js")
end

Nested Base URLs

You can organize imports from different sources using nested with(base:) blocks:

IMPORT_MAP = Utopia::ImportMap.build do |map|
	# Local components
	map.with(base: "/_components/") do |local|
		local.import "app", "./app.js"
	end
	
	# CDN imports
	map.with(base: "https://cdn.jsdelivr.net/npm/") do |cdn|
		cdn.import "lit", "lit@2.7.5/index.js"
		cdn.import "lit/decorators.js", "lit@2.7.5/decorators.js"
	end
end

Subresource Integrity

Add integrity hashes for enhanced security:

IMPORT_MAP = Utopia::ImportMap.build do |map|
	map.import("react", "https://esm.sh/react@18", integrity: "sha384-...")
end

Scoped Imports

Use scopes to resolve imports differently based on the referrer URL (the page or module location where the import is being made):

IMPORT_MAP = Utopia::ImportMap.build do |map|
	map.import("utils", "/utils.js")
	
	# When importing from any page under /admin/, use a different utils module
	map.scope("/admin/", {"utils" => "/admin/utils.js"})
end

When you're on a page at /admin/dashboard and you import "utils", it will resolve to /admin/utils.js. On other pages, it resolves to /utils.js.

Traditional JavaScript

You can also use JavaScript by embedding it directly into your HTML, or by creating a JavaScript source file and referencing that.

Embedding Code

When embedding JavaScript directly in XRB templates, wrap the code in CDATA comments to prevent XRB's parser from interpreting special characters like <, >, and &:

<html>
	<body>
		<script type="text/javascript">
			// <![CDATA[
			console.log("Hello World")
			// ]]>
		</script>
	</body>
</html>

External Script

In script.js:

console.log("Hello World")

In your HTML view:

<html>
	<body>
		<script type="text/javascript" src="script.js"></script>
	</body>
</html>