Skip to content

πŸŽ‹ Prepend a one-line banner comment with license notice to distribution files (CLI for package.json scripts)

License

Notifications You must be signed in to change notification settings

center-key/add-dist-header

Repository files navigation

Add Dist Header

logo

Prepend a one-line banner comment (with license notice) to distribution files

License:MIT npm Build

add-dist-header uses the name, homepage, and license from your project's package.json file to create a header comment and prepend it to a build file.

screenshot

Example header comment for a .js file:

//! my-app v3.1.4 ~~ https://github.com/my-org/my-app ~~ MIT License

Example header comment for a .css file:

/*! my-app v3.1.4 ~~ https://github.com/my-org/my-app ~~ MIT License */

Example header comment for a .xml file:

<!-- my-app v3.1.4 ~~ https://github.com/my-org/my-app ~~ MIT License -->

Header comments are only prepended to text files.Β  Binary files are ignored (unless the --all-files flag is specified).

Automatically prepending headers to distribution files is particularly handy when your build tools are configured to remove comments (such as if "removeComments": true in set in tsconfig.json). For a real-world example, see the files in the dist folder at w3c-html-validator

A) Setup

Install package for node:

$ npm install --save-dev add-dist-header

B) Usage

1. npm package.json scripts

Run dist-header from the "scripts" section of your package.json file.

Parameters:

  • The first parameter is the source file (defaults to "build/*").
  • The second parameter is the output folder (defaults to "dist").

Example package.json script:

   "scripts": {
      "add-headers": "add-dist-header build dist"
   },

2. Command-line npx

Example terminal commands:

$ npm install --save-dev add-dist-header
$ npx add-dist-header "build" "dist"
[17:13:50] add-dist-header build/my-app.d.ts --> dist/my-app.d.ts (413.11 KB)
[17:13:51] add-dist-header build/my-app.js --> dist/my-app.js (1,569.70 KB)

The parameters are optional:

$ add-dist-header  #same as above since "build/*" "dist" are the default parameter values
[17:13:50] add-dist-header build/my-app.d.ts --> dist/my-app.d.ts (413.11 KB)
[17:13:51] add-dist-header build/my-app.js --> dist/my-app.js (1,569.70 KB)
$ add-dist-header "meta/config.js"  #creates "dist/config.js" prepended with header
[17:15:03] add-dist-header meta/config.js --> dist/config.js (3.91 KB)

You can also install add-dist-header globally (--global) and then run it anywhere directly from the terminal.

3. CLI flags

Command-line flags:

Flag Description Values Default
--all-files Add headers to text files and just copy binary files. N/A N/A
--delimiter Characters separating the parts of the header comment. string ~~
--ext Filter files by file extension, such as .js.
Use a comma to specify multiple extensions.
string N/A
--keep-first Do not delete the original first line comment. N/A N/A
--no-version Do not substitute occurrences of {{package.version}}
with the package.json version number.
N/A N/A
--note Place to add a comment only for humans. string N/A
--quiet Suppress informational messages. N/A N/A
--recursive Include subfolders of the source folder. N/A N/A

Version number substitution:

In addition to prepending the header comment, add-dist-header also replaces all occurrences of {{package.version}} in each file with the version number found in package.json. This enables inserting the current package version number into your distribution files.

The substitution feature is disabled with the --no-version flag.

Examples:

  • add-dist-header build/minimized dist
    Copy the files in the build/minimized folder to the dist folder and add comment headers.

  • add-dist-header build/minimized dist --all-files
    Same as above command except that binary files, such as .png files, will also be copied over unmodified.

  • add-dist-header build dist --no-version --delimiter=πŸ”₯
    Add comment headers but do not substitute the version number and use "πŸ”₯" as the separator in the header comment instead of "~~".

  • add-dist-header build dist --no-version '--delimiter= --- '
    Specify a delimiter with a leading and trailing space.

  • add-dist-header build dist --ext=.js,.css --recursive
    Process only JavaScript and CSS files in the build folder and its subfolders.

Note: Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows.

C) Application Code

Even though add-dist-header is primarily intended for build scripts, the package can be used programmatically in ESM and TypeScript projects.

Example:

import { addDistHeader } from 'add-dist-header';

const options = {
   dist:      'dist',
   delimiter: 'πŸš€πŸš€πŸš€',
   };
const result = addDistHeader.prepend('build/rocket.js', options);
console.log('The size of the new file is:', result.size);

See the TypeScript Declarations at the top of add-dist-header.ts for documentation.



CLI Build Tools for package.json

  • πŸŽ‹ add-dist-header:Β  Prepend a one-line banner comment (with license notice) to distribution files
  • πŸ“„ copy-file-util:Β  Copy or rename a file with optional package version number
  • πŸ“‚ copy-folder-util:Β  Recursively copy files from one folder to another folder
  • πŸͺΊ recursive-exec:Β  Run a command on each file in a folder and its subfolders
  • πŸ” replacer-util:Β  Find and replace strings or template outputs in text files
  • πŸ”’ rev-web-assets:Β  Revision web asset filenames with cache busting content hash fingerprints
  • πŸš† run-scripts-util:Β  Organize npm package.json scripts into groups of easy to manage commands
  • 🚦 w3c-html-validator:Β  Check the markup validity of HTML files using the W3C validator

Feel free to submit questions at:
github.com/center-key/add-dist-header/issues

MIT License