importmap

Overview ¶

Command importmap vendors front-end packages at build time, for an application to embed and load with importmap.FromFS, without network access at run time.

importmap vendor [-config importmap.json] [-out assets/vendor] [-timeout 2m] [-local]
importmap verify [-out assets/vendor] [-root dir]

vendor downloads the packages of the configuration into the out directory, with their licences, and writes importmap.lock.json there with each file's source and SHA-384 integrity. With -local it only records the integrity of local packages again, without network access, for example after a build changed a bundle. verify checks the files against the lock without network access, for CI; when local files are outside the out directory, -root names a directory that holds both, such as the parent of out.

It suits go:generate:

//go:generate go run github.com/donseba/go-importmap/cmd/importmap vendor -config importmap.json -out assets/vendor

The configuration lists the packages:

{
  "provider": "cdnjs",
  "packages": [
    {
      "name": "htmx.org",
      "version": "4.0.0",
      "provider": "jsdelivr",
      "require": [{"file": "dist/htmx.esm.min.js", "as": "htmx"}]
    },
    {"name": "lib.js", "url": "https://example.com/lib.js", "as": "lib", "license": "https://example.com/LICENSE"}
  ]
}

provider is cdnjs (the default), jsdelivr, jsdelivr-esm, unpkg, skypack or esmsh. A package with url is that one file, saved under its name. require selects files by pattern, as library.Include does, and names them with as; raw maps a name to a URL left on its host. license is a file of the package or a URL; without it a LICENSE, LICENCE or COPYING file of the package is copied when there is one.

A package with "local": true holds files the application builds itself, such as a bundle: require lists them by their paths relative to the out directory (which may start with "../"), with as to import them by, and license is such a path too. They are not downloaded; the lock records their integrity, so FromFS and verify check them:

{"name": "editor", "local": true, "require": [{"file": "../editor/bundle.js"}], "license": "../editor/LICENSES.txt"}