@fnet/npm-package-extract

Introduction

The @fnet/npm-package-extract is a simple utility designed to fetch and extract npm packages directly from the npm registry. It allows users to download any version of a specified npm package, extract its content, and optionally install its dependencies. This tool can be useful for developers who need offline access to package contents or want to explore the package structure without the need to use it directly in their project immediately.

How It Works

The utility works by first fetching the metadata of a specified npm package from the npm registry. It checks for the available versions and either selects the latest or a specific version as requested by the user. Once identified, it downloads the corresponding tarball file of the package, extracts it to a specified directory, and optionally renames the extracted directory to a more descriptive name. Users can also choose to keep or remove the downloaded tarball and install package dependencies if desired.

Key Features

• Fetches metadata and tarballs directly from the npm registry.
• Supports downloading a specific version or the latest version of a package.
• Extracts the package contents to a specified directory.
• Allows for optional renaming of extracted contents for clarity.
• Provides options to retain the original tarball file.
• Can automatically install package dependencies excluding dev dependencies.

Conclusion

The @fnet/npm-package-extract tool provides a straightforward method for extracting and managing npm packages locally. It's a handy utility for developers who need more control over package assets on their file system or require its structure offline. Its functionality is simple to use, allowing users to seamlessly integrate it into their workflows without much hassle.

@fnet/npm-package-extract Developer Guide

Overview

@fnet/npm-package-extract is a utility library designed to simplify the process of downloading and extracting npm packages. Developers can use this library to programmatically fetch specific versions of npm packages, extract their contents, and optionally install their dependencies. This can be particularly useful for managing package contents outside the typical npm workflow, such as in scenarios where package exploration or customized installations are needed.

Installation

The library can be installed via npm or yarn. Use the following commands:

Using npm:

npm install @fnet/npm-package-extract

Using yarn:

yarn add @fnet/npm-package-extract

Usage

The library exports a single default function, which facilitates the fetching and extraction process. Below is a basic guide on how to implement it:

import npmPackageExtract from '@fnet/npm-package-extract';

(async () => {
  try {
    const result = await npmPackageExtract({
      name: 'express', // Name of the package
      ver: '4.17.1',   // Specific version, or 'latest'
      keep: false,     // Determines whether to keep the tarball
      output: './downloads',  // Output directory for the extracted contents
      install: true,   // If true, installs dependencies in the extracted directory
      rename: true     // Renames the extracted directory
    });

    console.log(`Package extracted to: ${result.output}`);
  } catch (error) {
    console.error('Extraction failed:', error);
  }
})();

Examples

Example 1: Basic Extraction

This example demonstrates a straightforward extraction of an npm package:

import npmPackageExtract from '@fnet/npm-package-extract';

npmPackageExtract({
  name: 'lodash',
  ver: 'latest',
  keep: false,
  output: './lodash-package'
}).then(result => {
  console.log(`Lodash extracted to: ${result.output}`);
}).catch(console.error);

Example 2: Extract and Install Dependencies

This example shows how to extract a package and install its dependencies:

import npmPackageExtract from '@fnet/npm-package-extract';

npmPackageExtract({
  name: 'react',
  ver: '^17.0.0',
  install: true,  // Installs package dependencies
  output: './react-package'
}).then(result => {
  console.log(`React extracted and dependencies installed at: ${result.output}`);
}).catch(console.error);

Acknowledgement

We acknowledge the node-fetch, tar, semver, and shelljs libraries for enabling core functionalities such as making HTTP requests, handling file extractions, semantic versioning, and shell command execution. These utilities underlie the robust operations of the @fnet/npm-package-extract library.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  name:
    type: string
    description: The name of the npm package.
  ver:
    type: string
    description: The version of the package to download, or 'latest'.
    default: latest
  keep:
    type: boolean
    description: Whether to keep the downloaded tarball file after extraction.
    default: false
  output:
    type: string
    description: Output directory where the package will be extracted.
  install:
    type: boolean
    description: Whether to run npm install after extraction.
    default: false
  rename:
    type: boolean
    description: Whether to rename the extracted directory.
    default: true
required:
  - name