npm

title: Downloading NPM package
types:
  DownloadNPMPackageResult: './npm.md#result'

Downloading NPM package

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

Function [func]downloadNPMPackage() downloads NPM package.

Unlike [bash]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:

• [prop]options, [type]object. Options, see below.

Function returns:

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

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

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

Options

Options object has the following mandatory properties:

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

and the following optional properties:

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

ifModifiedSince

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

Value can be one of the following:

• Version as [type]string. You can get it from [prop]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 [prop]target directory.
• [type]DownloadNPMPackageResult value from previous run.

If package has not been updated, function will return string [str]not_modified.

If option is not set, function cannot return [str]not_modified.

Result

Result object has the following properties:

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

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

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

Example

src: libraries/tools/package/npm.ts
title: 'example.ts'