@alessiofrittoli/node-scripts

Node.js Scripts 🫧

Utility library with common Node.js scripts

Table of Contents

• Getting started
• API Reference
  • Post-Install scripts
    • TypeScript Type Reference Management
      • Type Reference Interfaces
        • CommonOptions
        • AddTypesReferenceOptions
      • Type Reference Functions
        • createReferenceFile
        • updateTsConfig
        • addTypesReference
      • Add Types Reference Example usage
  • Release Scripts
    • Release
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using node-scripts in your projects:

npm i @alessiofrittoli/node-scripts

or using pnpm

pnpm i @alessiofrittoli/node-scripts

API Reference

Post-Install scripts

TypeScript Type Reference Management

The addTypesReference function allows you to create and manage TypeScript reference files and update the related tsconfig.json file for a project installing your node module.

Below are the detailed descriptions of the interfaces and functions included.

Type Reference Interfaces

CommonOptions

Properties

Property	Type	Description
root	string	The root directory of the project which is installing your node module.
name	string	The name of your node module.
outputFile	string	The output file name.

AddTypesReferenceOptions

Properties

Property	Type	Default	Description
name	string	-	The project name currently executing the script.
outputFile	string	'alessiofrittoli-env.d.ts'	The *.d.ts output file name.

Type Reference Functions

createReferenceFile

Creates or updates a reference file with type definitions for a project.

Parameters

Parameter	Type	Description
options	CommonOptions	Common options for the reference file creation.

• See CommonOptions interface.

Returns

void

Throws

Error - Throws an error if there is an issue creating or updating the file.

updateTsConfig

Updates the tsconfig.json file by adding the specified output file to the include array.

Parameters

Parameter	Type	Description
options	CommonOptions	Common options for the reference file creation.

• See CommonOptions interface.

Returns

void

Throws

Error - Throws an error if the tsconfig.json file cannot be read or updated.

addTypesReference

Adds a TypeScript reference file and updates the tsconfig.json for the project installing your node module.

If the options.outputFile already exists, it will be updated with the new package reference if not already in there.

Parameters

Parameter	Type	Description
options	AddTypesReferenceOptions	The options for adding the types reference.

• See AddTypesReferenceOptions interface.

Returns

void

Error

Exit the process with code 1 on failure.

Add Types Reference Example usage

Add the postinstall script in your package.json file which will execute the script once your package get installed in an external project.

{
    // ...
    "files": [
        // ...,
        "path-to-my-scripts" // ensure folder is published to `npm`
    ],
    "scripts": {
        // ...
        "postinstall": "node path-to-my-scripts/ts-setup.js"
    }
}

Then in your ts-setup.js file simply import the script and execute it with a few options.

// path-to-my-scripts/ts-setup.js
const {
    addTypesReference,
} = require("@alessiofrittoli/node-scripts/postinstall");
const project = require("../../package.json");

addTypesReference({
    name: project.name,
    outputFile: `${project.name}.d.ts`, // optional
});

Or you can statically pass a outputFile to add all your scoped packages in a single file.

// path-to-my-scripts/ts-setup.js
const {
    addTypesReference,
} = require("@alessiofrittoli/node-scripts/postinstall");
const project = require("../../package.json");

addTypesReference({
    name: project.name,
    outputFile: "my-package-scope-env.d.ts",
});

Release scripts

release

The release function automates the process of building, tagging, and optionally releasing a project to npm.

This function either works with process options (passed via CLI) or function arguments (function arguments takes precedence over process options).

Arguments

Argument	Type	Default	Description
version	string	--version process option or package.json.	The version to release.
			Retrieved from --version process option or package.json if omitted.
build	string	'build'	A custom build command that will build your project before publish.
			Retrieved from --build process option or fallback to build if omitted.
verbose	boolean	false	Enables detailed logging.
			Retrieved from --verbose process option or fallback to false if omitted.
origin	string	'origin'	The Git origin name used for pushing version tags.
			Retrieved from --origin or --o process option or fallback to origin if omitted.
npm	boolean	false	Indicates whether to publish the package to npm.
			Retrieved from --npm process option or fallback to false if omitted.
access	public|restricted	'public'	Sets npm package access level.
			Retrieved from --access process option or fallback to public if omitted.

Process Options - CLI

Option	Type	Default	Description
--version	string	Value from package.json	The version to release. Retrieved from package.json if omitted.
			Retrieved from package.json if omitted.
--build	string	build	A custom build command that will build your project before publish.
--verbose	boolean	false	Enables detailed logging.
--origin, -o	string	'origin'	The Git origin name used for pushing version tags.
--npm	boolean	false	Indicates whether to publish the package to npm.
--access	public|restricted	'public'	Sets npm package access level.

Performed steps

• Retrieve package.json:
  • Attempts to load and parse the package.json file.
  • Exits the process with code "1" if the file is unavailable or invalid.
  • Retrieve the version to use as fallback if no --version option has been provided.
• Parse Options:
  • Retrieves CLI options using getProcessOptions().
  • Validates critical parameters such as version and access.
• Prepare Git and Build:
  • Stashes any uncommitted changes with a stash name (pre-release).
  • Executes the npm run build or pnpm build command (if pnpm is globally installed).
  • Create the Git Tag as v{version}
  • Push the Git Tag the the specified origin or to the default Git Repository Remote.
• Publish to npm (Optional):
  • Publishes the package using npm publish if the --npm flag is set.
• Restore Stash:
  • Restores the stashed changes if any were saved during the process.
• Verbose Logging:
  • Logs details of the release process if the --verbose flag is set.

Example usage

Using function arguments

Add the release script in your package.json file so you can easly run from your terminal.

{
    // ...
    "scripts": {
        // ...
        "release": "node path-to-my-scripts/release.js"
    }
}

Then in your release.js file simply import the script and execute it.

⚠️ Remember to add this file to .npmignore so it won't be published within you package.

// path-to-my-scripts/release.js
require("@alessiofrittoli/node-scripts/release").release({
    verbose: true,
    npm: true,
    access: "restricted",
});

Using CLI options

Add the release script in your package.json file so you can easly run from your terminal.

{
    // ...
    "scripts": {
        // ...
        "release": "node path-to-my-scripts/release.js --verbose --npm --access restricted"
    }
}

Then in your release.js file simply import the script and execute it.

⚠️ Remember to add this file to .npmignore so it won't be published within you package.

// path-to-my-scripts/release.js
require("@alessiofrittoli/node-scripts/release").release();

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]