The URL to use for resolutions without a parent context.

Defaults to mapUrl or the process base URL.

Also determines the default scoping base for the import map when flattening.

Whether to use a local FS cache for fetched modules. Set to 'offline' to use the offline cache.

By default a global fetch cache is maintained between runs on the file system.

This caching can be disabled by setting cache: false.

When running offline, setting cache: 'offline' will only use the local cache and not touch the network at all, making fully offline workflows possible provided the modules have been seen before.

Support tracing CommonJS dependencies locally. This is necessary if you are using the "nodemodules" provider and have CommonJS dependencies. Disabled by default.

Custom provider definitions.

When installing from a custom CDN it can be advisable to define a custom provider in order to be able to get version deduping against that CDN.

Custom provider definitions define a provider name, and the provider instance consisting of three main hooks:

• pkgToUrl({ registry: string, name: string, version: string }, layer: string) -> String URL: Returns the URL for a given exact package registry, name and version to use for this provider. If the provider is using layers, the layer string can be used to determine the URL layer (where the defaultProvider: '[name].[layer]' form is used to determine the layer, eg minified v unminified etc). It is important that package URLs always end in /, because packages must be treated as folders not files. An error will be thrown for package URLs returned not ending in /.
• parsePkgUrl(url: string) -> { { registry: string, name: string, version: string }, layer: string } | undefined: Defines the converse operation to pkgToUrl, converting back from a string URL into the exact package registry, name and version, as well as the layer. Should always return undefined for unknown URLs as the first matching provider is treated as authoritative when dealing with multi-provider installations.
• resolveLatestTarget(target: { registry: string, name: string, range: SemverRange }, unstable: boolean, layer: string, parentUrl: string) -> Promise<{ registry: string, name: string, version: string } | null>: Resolve the latest version to use for a given package target. unstable indicates that prerelease versions can be matched. The definition of SemverRange is as per the sver package. Returning null corresponds to a package not found error.

The use of pkgToUrl and parsePkgUrl is what allows the JSPM Generator to dedupe package versions internally based on their unique internal identifier [registry]:[name]@[version] regardless of what CDN location is used. URLs that do not support parsePkgUrl can still be installed and used fine, they just do not participate in version deduping operations.

Example

const unpkgUrl = 'https://unpkg.com/';
const exactPkgRegEx = /^((?:@[^/\\%@]+/)?[^./\\%@][^/\\%@]*)@([^/]+)(/.*)?$/;

const generator = new Generator({
  defaultProvider: 'custom',
  customProviders: {
    custom: {
      pkgToUrl ({ registry, name, version }) {
        return `${unpkgUrl}${name}@${version}/`;
      },
      parseUrlPkg (url) {
        if (url.startsWith(unpkgUrl)) {
          const [, name, version] = url.slice(unpkgUrl.length).match(exactPkgRegEx) || [];
          return { registry: 'npm', name, version };
        }
      },
      resolveLatestTarget ({ registry, name, range }, unstable, layer, parentUrl) {
        return { registry, name, version: '3.6.0' };
      }
    }
  }
});

await generator.install('custom:jquery');

The provider to use for top-level (i.e. root package) installs if there's no context in the inputMap. This can be used to set the provider for a new import map. To use a specific provider for an install, rather than relying on context, register an override using the 'providers' option.

Supports: 'jspm.io' | 'jspm.io#system' | 'nodemodules' | 'skypack' | 'jsdelivr' | 'unpkg' | 'esm.sh';

Providers are responsible for resolution from abstract package names and version ranges to exact URL locations.

Providers resolve package names and semver ranges to exact CDN package URL paths using provider hooks.

These hooks include version resolution and converting package versions into URLs and back again.

See src/providers/[name].ts for how to define a custom provider.

New providers can be provided via the customProviders option. PRs to merge in providers are welcome as well.

The default registry to use when no registry is provided to an install. Defaults to 'npm:'.

Registries are separated from providers because multiple providers can serve any public registry.

Internally, the default providers for registries are handled by the providers object

The conditional environment resolutions to apply.

The conditions passed to the env option are environment conditions, as supported by Node.js in the package exports field.

By default the "default", "require" and "import" conditions are always supported regardless of what env conditions are provided.

In addition the default conditions applied if no env option is set are "browser", "development" and "module".

Webpack and RollupJS support a custom "module" condition as a bundler-specific solution to the dual package hazard, which is by default included in the JSPM resolution as well although can be turned off if needed.

Note when providing custom conditions like setting env: ["production"] that the "browser" and "module" conditions still need to be applied as well via env: ["production", "browser", "module"]. Ordering does not matter though.

Any other custom condition strings can also be provided.

User-provided fetch options for fetching modules, check https://github.com/npm/make-fetch-happen#extra-options

Allows ignoring certain module specifiers during the tracing process. It can be useful, for example, when you provide an inputMap that contains a mapping that can't be traced in current context, but you know it will work in the context where the generated map is going to be used.

const generator = new Generator({
  inputMap: {
      imports: {
          "react": "./my/own/react.js",
      }
  },
  ignore: ["react"]
});

// Even though `@react-three/fiber@7` depends upon `react`,
// `generator` will not try to trace and resolve `react`,
// so the mapping provided in `inputMap` will end up in the resulting import map.
await generator.install("@react-three/fiber@7")

An authoritative initial import map.

An initial import map to start with - can be from a previous install or to provide custom mappings.

Whether to include "integrity" field in the import map

Lockfile data to use for resolutions

The URL of the import map itself, used to construct relative import map URLs.

Defaults to the base URL.

The mapUrl is used in order to output relative URLs for modules located on the same host as the import map.

E.g. for mapUrl: 'file:///path/to/project/map.importmap', installing local file packages will be output as relative URLs to their file locations from the map location, since all URLs in an import map are relative to the URL of the import map.

A map of custom scoped providers.

The provider map allows setting custom providers for specific package names, package scopes or registries. For example, an organization with private packages with names like npmpackage and @orgscope/... can define the custom providers to reference these from a custom source:

  providers: {
    'npmpackage': 'nodemodules',
    '@orgscope': 'nodemodules',
    'npm:': 'nodemodules'
  }

Alternatively a custom provider can be referenced this way for eg private CDN / registry support.

Custom dependency resolution overrides for all installs.

The resolutions option allows configuring a specific dependency version to always be used overriding all version resolution logic for that dependency for all nestings.

It is a map from package name to package version target just like the package.json "dependencies" map, but that applies and overrides universally.

Example

const generator = new Generator({
  resolutions: {
    dep: '1.2.3'
  }
});

It is also useful for local monorepo patterns where all local packages should be located locally. When referencing local paths, the baseUrl configuration option is used as the URL parent.

const generator = new Generator({
  mapUrl: new URL('./app.html', import.meta.url),
  baseUrl: new URL('../', import.meta.url),
  resolutions: {
    '@company/pkgA': `./pkgA`,
    '@company/pkgB': `./pkgB`
    '@company/pkgC': `./pkgC`
  }
})

All subpath and main resolution logic will follow the package.json definitions of the resolved package, unlike inputMap which only maps specific specifiers.

The URL to treat as the root of the serving protocol of the import map, used to construct absolute import map URLs.

When set, rootUrl takes precendence over mapUrl and is used to normalize all import map URLs as absolute paths against this URL.

E.g. for rootUrl: 'file:///path/to/project/public', any local module public/local/mod.js within the public folder will be normalized to /local/mod.js in the output map.

Support tracing TypeScript dependencies when generating the import map. Disabled by default.