https://github.com/center-key/add-dist-header
🎋 Prepend a one-line banner comment with license notice to distribution files (CLI for package.json scripts)
https://github.com/center-key/add-dist-header
banner cli directory dist distribution file folder header npm prepend
Last synced: 23 days ago
JSON representation
🎋 Prepend a one-line banner comment with license notice to distribution files (CLI for package.json scripts)
- Host: GitHub
- URL: https://github.com/center-key/add-dist-header
- Owner: center-key
- License: mit
- Created: 2021-09-28T00:45:13.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-04T02:16:20.000Z (27 days ago)
- Last Synced: 2025-05-07T22:06:42.519Z (23 days ago)
- Topics: banner, cli, directory, dist, distribution, file, folder, header, npm, prepend
- Language: TypeScript
- Homepage:
- Size: 623 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Add Dist Header
_Prepend a one-line banner comment (with license notice) to distribution files_
[](https://github.com/center-key/add-dist-header/blob/main/LICENSE.txt)
[](https://www.npmjs.com/package/add-dist-header)
[](https://github.com/center-key/add-dist-header/actions/workflows/run-spec-on-push.yaml)
**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.
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](https://github.com/center-key/w3c-html-validator/tree/main/dist)
## A) Setup
Install package for node:
```shell
$ 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:
```json
"scripts": {
"add-headers": "add-dist-header build dist"
},
```
### 2. Command-line npx
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. 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:
``` typescript
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](src/add-dist-header.ts) for documentation.
---
**CLI Build Tools for package.json**
- 🎋 [add-dist-header](https://github.com/center-key/add-dist-header): _Prepend a one-line banner comment (with license notice) to distribution files_
- 📄 [copy-file-util](https://github.com/center-key/copy-file-util): _Copy or rename a file with optional package version number_
- 📂 [copy-folder-util](https://github.com/center-key/copy-folder-util): _Recursively copy files from one folder to another folder_
- 🪺 [recursive-exec](https://github.com/center-key/recursive-exec): _Run a command on each file in a folder and its subfolders_
- 🔍 [replacer-util](https://github.com/center-key/replacer-util): _Find and replace strings or template outputs in text files_
- 🔢 [rev-web-assets](https://github.com/center-key/rev-web-assets): _Revision web asset filenames with cache busting content hash fingerprints_
- 🚆 [run-scripts-util](https://github.com/center-key/run-scripts-util): _Organize npm package.json scripts into groups of easy to manage commands_
- 🚦 [w3c-html-validator](https://github.com/center-key/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](https://github.com/center-key/add-dist-header/issues)
[MIT License](LICENSE.txt)