Add Dist Header

_Prepend a one-line banner comment (with license notice) to distribution files_


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.

width=800 alt=screenshot>

Example header comment for a .js file:
``javascript
//! my-app v3.1.4 ~~ https://github.com/my-org/my-app ~~ MIT License
`
Example header comment for a .css file:
`css
/! my-app v3.1.4 ~~ https://github.com/my-org/my-app ~~ MIT License /
`
Example header comment for a .xml file:
`xml

`

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:
`shell
$ npm install --save-dev add-dist-header
`

B) Usage

$3

`
add-dist-header [SOURCE] [TARGET]
`
Parameters:
The first parameter is the source file (defaults to "build/").
The second parameter is the output* folder (defaults to "dist").

$3

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

Example package.json script:
`json
"scripts": {
"add-headers": "add-dist-header build dist"
},
`

$3


Example terminal commands:
`shell
$ 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:
`shell
$ 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

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 |
| --new-ext | Rename target files to use the specificed file extention. | string | 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.

$3


- 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.

- add-dist-header build dist --ext=.css --new-ext=.style.css

Process only CSS files and change the .css file extension to .style.css for each target file.

> [!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:
` typescript
import { addDistHeader } from 'add-dist-header';

const options = {
dist: 'dist',
delimiter: '🚀🚀🚀',
};
const result = addDistHeader.prepend('build/rocket.js', options);
console.info('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