Downloading NPM package

This tutorial is part of package functions documentation in Iconify Tools.

Function downloadNPMPackage() downloads NPM package.

Unlike npm install, this function downloads and extracts only requested NPM package, it does not install dependencies and does not run any scripts.

Usage

Function has the following parameter:

• options, object. Options, see below.

Function returns:

• DownloadNPMPackageResult object on success.
• "not_modified" string if repository has not been updated since last run (can be returned only if ifModifiedSince option is set).

In case of error, function might throw an exception, which you can catch using try and catch.

Function is asynchronous. That means you need to handle it as Promise instance, usually by adding await before function call.

Options

Options object has the following mandatory properties:

• target, string. Target directory. If directory is missing, it will be created.
• package, string. Package name.

and the following optional properties:

• tag, string. NPM tag. Default is "latest".
• cleanup, boolean. If true, target directory will be emptied before exporting icons. Default is false.
• ifModifiedSince, string|true|DownloadNPMPackageResult. If set, function will check if repository has been updated.

ifModifiedSince

Option ifModifiedSince is used when you want to retrieve data only if repository has been updated.

Value can be one of the following:

• Version as string. You can get it from version property of result of previous run.
• If value is true, function compare latest version in NPM registry with version from previously downloaded files in target directory.
• DownloadNPMPackageResult value from previous run.

If package has not been updated, function will return string "not_modified".

If option is not set, function cannot return "not_modified".

Result

Result object has the following properties:

• downloadType = "npm".
• rootDir, string. Target directory. It is normalized version of target option, without trailing "/".
• contentsDir, string. Directory where archive was unpacked.
• version, string. Package version.

Value is contentsDir always contains rootDir because archives are unpacked in sub-directory of rootDir. For example:

json{
   "downloadType": "npm",
   "rootDir": "output/npm-test",
   "contentsDir": "output/npm-test/package",
   "version": "1.0.1"
}

Example

example.ts

tsimport { downloadNPMPackage } from '@iconify/tools';

(async () => {
   console.log(
       await downloadNPMPackage({
           target: 'downloads/icon-sets/mdi-light',
           package: '@iconify-json/mdi-light',
       })
   );
})();