generatePackageBanner - Build Tools

Overview

generatePackageBanner generates a standardized banner comment using metadata from the nearest package.json file or a provided package object.

It automatically resolves package information, applies safe fallbacks for missing fields, and returns a consistent, readable banner suitable for bundled or distributed output files.

Resolved banner fields include:
- Title ➔ options.title, otherwise package.json.name, otherwise Unknown Package.
- Version ➔ package.json.version, otherwise Unknown.
- Author ➔ options.author, package.json.author, or package.json.author.name, otherwise Unknown.
- Repository ➔ package.json.homepage, repository, or repository.url (normalized), otherwise Unknown.
Additional behavior:
- Automatically strips git+ prefixes from repository URLs.
- Automatically removes trailing .git suffixes.
- Supports optional final newline output via withEof.

Why use this?

Automatically reads metadata from the nearest package.json.
Accepts a custom packageJson object when needed.
Provides safe fallbacks for missing fields.
Produces consistent banner output across builds.
Normalizes repository URLs automatically.
Supports optional final newline output.
Ideal for bundler banners (tsdown, tsup, rollup, esbuild, etc.).
Useful for generated artifacts and distributed library files.

Importing

import { generatePackageBanner } from "@rzl-zone/build-tools";

const { generatePackageBanner } = require("@rzl-zone/build-tools");

Syntax

generatePackageBanner(
  options?: GeneratePackageBannerOptions
): Promise<string>

generatePackageBanner(options?): Promise<string>

Parameters

Prop

Type

`options`

Optional configuration object that defines how the utility function should behave in various scenarios, allowing customization and greater control at runtime.

`title`

Description:
Display title shown in the banner.
Required:
Type:
string
Default:
string
Notes
- Defaults to the name field from package.json when available, otherwise return "Unknown Package".
Example:
TypeScript/JavaScript
await generatePackageBanner(["dist/**/*.js", "build/*/*.mjs"], { title: "@my-org/my-package" });

Notes

Invalid values or empty-string are automatically reset to default.

`author`

Description:
Author name displayed in the banner.

When omitted, attempts to resolve from:
1. author (If empty-string or unset will check to author.name).
2. author.name (If empty-string or unset will return "Unknown").
Required:
Type:
string
Default:
string
Example:
TypeScript/JavaScript
await generatePackageBanner(["dist/**/*.js", "build/*/*.mjs"], { author: "John Doe" });

Notes

Invalid values or empty-string are automatically reset to default.

`packageJson`

Description:
Custom package metadata used instead of the automatically loaded package.json.

Overrides the default behavior of loading package.json via getPackageJson().
Required:
Type:
object
Default:
Loaded from getPackageJson().
Notes
- Automatically locates and loads the nearest package.json.
- Throws an error if:
  
  No package.json is found.
  
  The file exists but contains invalid JSON.

Example:

TypeScript/JavaScript

await generatePackageBanner(["dist/**/*.js", "build/*/*.mjs"], {
  packageJson: {
    name: "@my-org/my-package",
    version: "1.2.3",
    author: "John Doe",
    homepage: "https://github.com/my-org/my-package"
  }
});

Notes

Invalid values are automatically reset to default.

`withEof`

Description:
Append an end-of-file newline to the banner output.
- When enabled, a trailing newline is appended to ensure:
  
  POSIX-compliant text files.
  
  Clean concatenation with subsequent source content.
  
  Consistent formatting during code injection.
Required:
Type:
boolean
Default:
true
Example:
TypeScript/JavaScript
await generatePackageBanner(["dist/**/*.js", "build/*/*.mjs"], { withEof: false });

Returns

Returns a Promise<string>.
The function performs asynchronous file processing and return a string value of banner generated.

Throws

Throws a built-in JavaScript error in the following cases:

No package.json file can be found while walking up the directory tree.
The located package.json contains invalid JSON and cannot be parsed.

Version information

Since: v0.0.7.
Category: generate.
Stability: ✅ Stable (Production-ready).

Made with ❤️ by @rzl-app