Class Generator

importMap

• get importMap(): ImportMap

  Returns ImportMap

constructor

• new Generator(opts?: GeneratorOptions): Generator

  Constructs a new Generator instance.

  Parameters

  • opts: GeneratorOptions = {}

    Configuration for the new generator instance.

  Returns Generator

  Example

  const generator = new Generator({
    mapUrl: import.meta.url,
    inputMap: {
      "imports": {
        "react": "https://cdn.skypack.dev/react"
      }
    },
    defaultProvider: 'jspm',
    defaultRegistry: 'npm',
    providers: {
      '@orgscope': 'nodemodules'
    },
    customProviders: {},
    env: ['production', 'browser'],
    cache: false,
  });
  Copy

addMappings

• addMappings(
      jsonOrHtml: string | IImportMap,
      mapUrl?: string | URL,
      rootUrl?: string | URL,
      preloads?: string[],
  ): Promise<string[]>

  Add new custom mappings and lock resolutions to the input map of the generator, which are then applied in subsequent installs.

  Parameters

  • jsonOrHtml: string | IImportMap

    The mappings are parsed as a JSON data object or string, falling back to reading an inline import map from an HTML file.
  • mapUrl: string | URL = ...

    An optional URL for the map to handle relative resolutions, defaults to generator mapUrl.
  • rootUrl: string | URL = ...

    An optional root URL for the map to handle root resolutions, defaults to generator rootUrl.
  • Optionalpreloads: string[]

  Returns Promise<string[]>

  The list of modules pinned by this import map or HTML.

getLock

• getLock(): LockResolutions

  Retrieve the lockfile data from the installer

  Returns LockResolutions

link

• link(
      specifier: string | string[],
      parentUrl?: string,
  ): Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

  Link a module, installing all dependencies necessary into the map to support its execution including static and dynamic module imports.

  Parameters

  • specifier: string | string[]

    Module or list of modules to link
  • OptionalparentUrl: string

    Optional parent URL

    Link specifiers are module specifiers - they can be bare specifiers resolved through package resolution, relative URLs, or full URLs, for example:

  Returns Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

  Example

  await generator.link(['react', './local.js']);
  Copy

  In the above, an import map will be constructed based on the resolution of react, and tracing all its dependencies in turn, as well as for the local module, and any dependencies it has in turn as well, installing all dependencies into the import map as needed.

  In general, using generator.link(entryPoints) is recommended over generator.install(), since it represents a real module graph linkage as would be required in a browser.

  By using link, we guarantee that the import map constructed is only for what is truly needed and loaded. Dynamic imports that are statically analyzable are traced by link.

linkHtml

• linkHtml(html: string | string[], htmlUrl?: string | URL): Promise<string[]>

  Links every imported module in the given HTML file, installing all dependencies necessary to support its execution.

  Parameters

  • html: string | string[]

    HTML to link
  • OptionalhtmlUrl: string | URL

    URL of the given HTML

  Returns Promise<string[]>

htmlInject

• htmlInject(
      html: string,
      opts?: {
          pins?: boolean | string[];
          trace?: boolean | string[];
          htmlUrl?: string | URL;
          rootUrl?: string | URL;
          preload?: boolean | "all" | "static";
          integrity?: boolean;
          whitespace?: boolean;
          esModuleShims?: string | boolean;
          comment?: string | boolean;
      },
  ): Promise<string>

  Inject the import map into the provided HTML source

  Parameters

  • html: string

    HTML source to inject into
  • opts: {
        pins?: boolean | string[];
        trace?: boolean | string[];
        htmlUrl?: string | URL;
        rootUrl?: string | URL;
        preload?: boolean | "all" | "static";
        integrity?: boolean;
        whitespace?: boolean;
        esModuleShims?: string | boolean;
        comment?: string | boolean;
    } = {}

    Injection options

  Returns Promise<string>

  HTML source with import map injection

install

• install(
      install: string | Install | (string | Install)[],
      mode?: InstallMode,
  ): any

  Install a package target into the import map, including all its dependency resolutions via tracing.

  Parameters

  • install: string | Install | (string | Install)[]

    Package or list of packages to install into the import map.
  • Optionalmode: InstallMode

    Install constraint mode.

    Passing no install list or an empty install list will reinsstall all top-level "imports" from the provided input import map.

  Returns any

  Example

  // Install a new package into the import map
  await generator.install('react-dom');
  
  // Install a package version and subpath into the import map (installs lit/decorators.js)
  await generator.install('lit@2/decorators.js');
  
  // Install a package version to a custom alias
  await generator.install({ alias: 'react16', target: 'react@16' });
  
  // Install a specific subpath of a package
  await generator.install({ target: 'lit@2', subpath: './html.js' });
  
  // Install an export from a locally located package folder into the map with multiple subpaths.
  // The package.json is used to determine the exports and dependencies.
  await generator.install({ alias: 'mypkg', target: './packages/local-pkg', subpaths: ['./feature1', './feature2'] });
  
  // Install all exports of the package, based on enumerating all the package export subpaths.
  await generator.install({ alias: 'mypkg', target: './packages/local-pkg', subpaths: true });
  Copy

• install(mode?: InstallMode): any

  Install a package target into the import map, including all its dependency resolutions via tracing.

  Parameters

  • Optionalmode: InstallMode

    Install constraint mode.

    Passing no install list or an empty install list will reinsstall all top-level "imports" from the provided input import map.

  Returns any

  Example

  // Install a new package into the import map
  await generator.install('react-dom');
  
  // Install a package version and subpath into the import map (installs lit/decorators.js)
  await generator.install('lit@2/decorators.js');
  
  // Install a package version to a custom alias
  await generator.install({ alias: 'react16', target: 'react@16' });
  
  // Install a specific subpath of a package
  await generator.install({ target: 'lit@2', subpath: './html.js' });
  
  // Install an export from a locally located package folder into the map with multiple subpaths.
  // The package.json is used to determine the exports and dependencies.
  await generator.install({ alias: 'mypkg', target: './packages/local-pkg', subpaths: ['./feature1', './feature2'] });
  
  // Install all exports of the package, based on enumerating all the package export subpaths.
  await generator.install({ alias: 'mypkg', target: './packages/local-pkg', subpaths: true });
  Copy

reinstall

• reinstall(): Promise<any>

  Locking install, retraces all top-level pins but does not change the versions of anything (similar to "npm ci").

  Returns Promise<any>

  Deprecated

  use generator.install('freeze') instead.

update

• update(
      pkgNames?: string | string[],
  ): Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

  Updates the versions of the given packages to the latest versions compatible with their parent's package.json ranges. If no packages are given then all the top-level packages in the "imports" field of the initial import map are updated.

  Parameters

  • OptionalpkgNames: string | string[]

    Package name or list of package names to update.

  Returns Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

uninstall

• uninstall(
      names: string | string[],
  ): Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

  Parameters

  • names: string | string[]

  Returns Promise<{ staticDeps: string[]; dynamicDeps: string[] }>

setVirtualSourceData

• setVirtualSourceData(baseUrl: string, fileData: SourceData): void

  Populate virtual source files into the generator for further linking or install operations, effectively intercepting network and file system requests to those URLs.

  Parameters

  • baseUrl: string

    base URL under which all file data is located
  • fileData: SourceData

    Key value pairs of file data strings or buffers virtualized under the provided URL base path,

  Returns void

  Example

  `"file:///path/to/package/"` or
  `"https://site.com/pkg@1.2.3/)"`.
  Copy

  Example

  {
    'package.json': '',
    'dir/file.bin': new Uint8Array([1,2,3])
  }
  Copy

publish

• publish(options: Publish): Promise<DeployOutput>

  Publish a package to a JSPM provider

  This function creates a tarball from the provided files and uploads it.

  Parameters

  • options: Publish

    Publish options

  Returns Promise<DeployOutput>

  Promise that resolves with the package URL, map URL, and an optional copy-paste code snippet demonstrating usage.

  Example

  import { Generator } from '@jspm/generator';
  
  const generator = new Generator({
    inputMap: { ...custom import map... }
  });
  const result = await generator.publish({
    package: './pkg',
    provider: 'jspm.io',
    importMap: true,
    link: true,
  });
  
  // URL to the published package and published import map
  console.log(result.packageUrl, result.mapUrl);
  // HTML code snippets demonstrating how to run the published code in a browser
  console.log(result.codeSnippets);
  Copy

  JSPM will fully link all dependencies when link: true is provided, and populate them into the import map of the generator instance provided to the publish.

  Alternatively, instead of a local package path, package can also be provided as a record of virtual sources.

auth

• auth(
      options?: {
          provider?: string;
          username?: string;
          verify?: (url: string, instructions: string) => void;
      },
  ): Promise<{ token: string }>

  Authenticate with a provider to obtain an authentication token.

  Parameters

  • options: {
        provider?: string;
        username?: string;
        verify?: (url: string, instructions: string) => void;
    } = {}

    Authentication options including provider, username, and verify callback

  Returns Promise<{ token: string }>

  Promise resolving to the authentication token

eject

• eject(
      __namedParameters: {
          name: string;
          version: string;
          registry?: string;
          provider?: string;
      },
      outDir: string,
  ): Promise<void>

  Eject a published package by downloading it to the provided local folder, and stitching its import map into the generator import map.

  Parameters

  • __namedParameters: { name: string; version: string; registry?: string; provider?: string }
  • outDir: string

  Returns Promise<void>

mergeMap

• mergeMap(map: IImportMap, mapUrl?: string): Promise<void>

  Merges an import map into this instance's import map.

  Performs a full retrace of the map to be merged, building out its version constraints separately, and expanding scopes previously flattened by the scope-flattening "flattenScopes" option that occurs by default for extracted import maps.

  Parameters

  • map: IImportMap
  • OptionalmapUrl: string

  Returns Promise<void>

clone

• clone(): Generator

  Create a clone of this generator instance with the same configuration.

  Does not clone the internal import map or install state.

  Returns Generator

extractMap

• extractMap(
      pins: string | string[],
      mapUrl?: string | URL,
      rootUrl?: string | URL,
      integrity?: boolean,
  ): Promise<{ map: IImportMap; staticDeps: string[]; dynamicDeps: string[] }>

  Extracts a smaller import map from a larger import map

  This is for the use case where one large import map is being used to manage dependencies across multiple entry points in say a multi-page application, and one pruned import map is desired just for a set of top-level imports which is smaller than the full set of top-level imports

  These top-level imports can be provided as a list of "pins" to extract, and a fully pruned map with only the necessary scoped mappings will be traced out of the larger map while respecting its resolutions.

  Parameters

  • pins: string | string[]
  • OptionalmapUrl: string | URL
  • OptionalrootUrl: string | URL
  • Optionalintegrity: boolean

  Returns Promise<{ map: IImportMap; staticDeps: string[]; dynamicDeps: string[] }>

resolve

• resolve(specifier: string, parentUrl?: string | URL): string

  Resolve a specifier using the import map.

  Parameters

  • specifier: string

    Module to resolve
  • parentUrl: string | URL = ...

    ParentURL of module to resolve

  Returns string

  Resolved URL string

getAnalysis

• getAnalysis(url: string | URL): ModuleAnalysis

  Parameters

  • url: string | URL

  Returns ModuleAnalysis

getMap

• getMap(mapUrl?: string | URL, rootUrl?: string | URL): IImportMap

  Obtain the final generated import map, with flattening and subpaths combined (unless otherwise disabled via the Generator flattenScopes and combineSubpaths options).

  A mapUrl can be provided typically as a file URL corresponding to the location of the import map on the file system. Relative paths to other files on the filesystem will then be tracked as map-relative and output as relative paths, assuming the map retains its relative relation to local modules regardless of the publish URLs.

  When a root URL is provided pointing to a local file URL, / prefixed URLs will be used for all modules contained within this file URL base as root URL relative instead of map relative URLs like the above.

  Parameters

  • OptionalmapUrl: string | URL
  • OptionalrootUrl: string | URL

  Returns IImportMap

traceMap

baseUrl

mapUrl

rootUrl

map

logStream

log

integrity

flattenScopes

combineSubpaths