What does it do?

The extension importmap is providing a middleware which is executed when a request is sent to the TYPO3 frontend. It hooks into the frontend controller and outputs four type of html-tags within the head-tag. These tags contain an importmap. That map is basically a JSON object with keys and links which are used to import ES modules at the top of javascript files.

The advent of HTTP2 requests have made the cost to send multiple HTTP requests quite insignificant. Importmaps utilize this performance boost while keeping the complexity of managing JavaScript ES modules low.

Which html-tags are generated?

Four type of html-tags are generated: The importmap, modulepreload link-tags, a shim to extend browser support, the "bootstrap" import statement for the application.

Features

Once installed this extension is automatically loaded on each frontend request. Simply specify a YAML configuration at the settings.yaml file within your site set. The needed html-tags are then generated.

A list of functions:

• Easy YAML configuration
• Support Bootstrapping through an starting import statement
• Easily preload modules through link-tags
• Override module names to keep visual order in YAML file

Install with composer

This extension is simply installed with one command over the comfortable composer command line:

composer require atkins/importmap

Install without composer (Legacy installations)

If you're using legacy systems without composer you can install it with the Extension Manager searching for the key importmap.

Clear cache

Make sure to clear your cache and rebuild the autoload information. At legacy installations both is done at the maintenance tab:

You can manually rebuild the autoload information at composer installation like so:

composer dumpautoload

Do do I configure my own importmap?

The importmap is configured by setting the key "importmap" at the page-attribute within your site sets configuration in your settings.yaml file:

page:
    importmap:
        # importmap definition comes here

The importmap definition always has an application key at which the path property is set. The application key always refers to the bootstrap script which is first executed. An configuration to bootstrap your application looks like this:

page:
    importmap:
        application:
            path: EXT:your_extension/Resources/Public/JavaScript/application.js

The application key is mandatory and only the path to the script has to be set. Note that it points to a Public path within the Resources folder of your provider extension.

How do I add further modules to the importmap?

You can add as many modules as you like with the following syntax:

page:
    importmap:
        moduleKey1:
            path: EXT:your_extension/Resources/Public/JavaScript/module1.js
        moduleKey2:
            path: EXT:your_extension/Resources/Public/JavaScript/module2.js

Make sure that the JS file is located under the Public folder.

How to find the ES module of your favorite JS library?

Any ES module can be used for the importmap. To download your favorite JS library you have to find the bundled version of it, download it under/to your extensions Public folder and reference it in the importmap definition. Feel free to use the following tool to find links to your ES module, goto JSPM Generator https://generator.jspm.io/. Add you library on the left hand side. An example could be: @hotwired/stimulus

After adding it you should see the URL to the module, copy the URL to your browser and download the JS file into your extensions Public/JavaScript/ folder. After that you reference it in your settings.yaml:

page:
 importmap:
     stimulusjs:
         path: EXT:your_extension/Resources/Public/JavaScript/stimulus.js

How do I preload modules?

Modules are preloadable. The extension generates a link-tag with a rel-attribute which signals the browsers to preload this module which makes running it even faster. As follows is an example of module preloading:

page:
 importmap:
     stimulusjs:
         path: EXT:your_extension/Resources/Public/JavaScript/stimulus.js
         preload: 1

How to override the module key used for importing?

Modules are referenced by the entry key of the module definition, e.g. page.importmap.stimulusjs Here is an example of how you might structure your TypoScript:

page:
 importmap:
     modules/stimulusjs:
         path: EXT:your_extension/Resources/Public/JavaScript/stimulus.js
         preload: 1
         override: stimulus
     controllers/header_controller:
         path: EXT:your_extension/Resources/Public/JavaScript/controllers/header_controller.js
         preload: 1

Now you could import the stimulus JS module with this command while keeping the YAML more organized and reflecting that structure within the Public folder:

import { Application } from 'stimulus'
import HeaderController from 'controllers/header_controller'

Where can I find working examples of a importmap implementation?

The Pagedoctor Starter extension is a good starting point to see the importmap in action. Checkout the extension repository here https://extensions.typo3.org/extension/pagedoctor_starter.

How to import modules in JavaScript?

The import statement has to be added to the top of your application file specified at importmap.application.path:

import { Application } from 'stimulus'
import Alpine from 'alpinejs'
import HeaderController from 'controllers/header_controller'

The corresponding YAML configuration would look like this:

page:
    importmap:
        application:
        path: EXT:your_extension/Resources/Public/JavaScript/application.js
        modules/stimulus:
            path: EXT:your_extension/Resources/Public/JavaScript/modules/stimulus-3.2.2.js
            preload: 1
            override: '@hotwired/stimulus'
        modules/turbo:
            path: EXT:your_extension/Resources/Public/JavaScript/modules/turbo-8.0.13.js
            preload: 1
            override: '@hotwired/turbo'
        modules/alpinejs:
            path: EXT:your_extension/Resources/Public/JavaScript/modules/alpinejs-3.14.9.js
            preload: 1
            override: alpinejs
        controllers/hello_controller:
            path: EXT:your_extension/Resources/Public/JavaScript/controllers/hello_controller.js