1.1.0 • Published 5 years ago

@khatastroffik/npm-preview-package v1.1.0

Weekly downloads
1
License
MIT
Repository
-
Last release
5 years ago

npm-preview-package

The "npm-previewpkg" CLI application generates an overview of the files and directories, which would be part of an npm package when published: a package content preview.

To be more precise, the utility displays the result provided by npm-packlist in a user friendly way.

features

The CLI application implements the following:

  • preview as "tree" (default)
  • preview as "list"
  • sorted output ("file explorer" like)
  • colored output
  • stats on files size
  • verbose (preview date, header generated out of the package.json content etc.) ???
  • TBD: template output (%previewdate%, %title%, %filelist% etc.) ???

Example output (showing usage of custom colors):

example output

requirements

  • node.js (circa version >= 8.x) is required to run the application.
  • npm (circa version >= 6.x) is used to install the application.
  • alternatives to npm (untested): yarn etc.

installation

Either globally (accessible from everywhere in the shell):

> npm install -g @khatastroffik/npm-preview-package

or locally (as a "development dependency"):

> npm install --save-dev @khatastroffik/npm-preview-package

usage

You may call the application according to the following schema:

  • if installed globally

    > npm-previewpkg [options] [path-to-the-package]
  • if installed locally

    > npx npm-previewpkg [options] [path-to-the-package]

options and parameter

argumenttypedescription
-l, --listoptionreturn a flat list instead of a treeview
-v, --versionoptionoutput the version of this application
-h, --helpoptiondisplay the help message describing the CLI usage
-d, --dark-colorsoptionuse dark colors (preset) for displaying the treeview
-b, --bright-colorsoptionuse bright colors (preset) for displaying the treeview
-c, --custom-colorsoptionuse custom colors for displaying the treeview
-tc, --text-color <color>optiondefine the custom color of the text. See "extended help"
-bc, --branch-color <color>optiondefine the custom color of the tree branches. See "extended help"
-eh, --extended-helpoptiondisplay extended help on "custom colors" and "Usage Examples"
[path-to-the-package]parameterthe path for which a content preview should be displayed.

All arguments are optional i.e. may be omitted. If the path parameter is not specified, then the current directory will be scanned instead i.e. the path default to ./.

Custom colors

All custom colors must match a standard CSS color name as defined by the W3C: W3C color names

The custom colors may be (pre-) defined as ENV (environment) variables like so (e.g.):

> set TreeifierTextColor=orange
> set TreeifierBranchColor=red

Hence, the allowed environment variables are:

  • TreeifierTextColor for a custom text color
  • TreeifierBranchColor for a custom color of the tree branches

In case any ENV variable is set prior to calling the application, then the option --custom-colors may be used without requiring that the text and/or branch colors are explicitly set in the call.

If the custom colors are not explicitly set in the call, then they default to their corresponding ENV values (if defined) or to the default color "lightgray".

Example calls:

  • scan the current directory i.e. ./ (default) $ npm-previewpkg

  • scan a specific directory (absolute or relative paths are permitted) $ npm-previewpkg ../some-other-app-directory

  • scan the current directory and display the result as an ordered list $ npm-previewpkg --list

  • display the preview using dark color mode $ npm-previewpkg --dark

  • display the preview using custom colors $ npm-previewpkg --text-color orange --branch-color red

  • display the preview using custom colors as defined per ENV variables (see above) $ npm-previewpkg --custom-colors

CI/CD

This tool could be used to document a package publication e.g. as part of a CI/CD workflow.

The CLI would not break the workflow, since it's only generating some text output in the command line (console). The output may be reused/redirected, though.

Example:

> npm-previewpkg --list > pre-publish-package-content.txt

license and repositories

  • License: MIT - Copyright (c) 2020 Loïs Bégué

  • Code Repository: The source code of this utility can be found in the following repository: GitHub :: npm-preview-package

  • Package Repository: The installable package containing the utility and the library is available at: NPM :: npm-preview-package

Note: To conform to the SoC principle (Separation of Concerns), the Github repository does not contain the build artifacts and the NPM repository does not contain the sources.