Package Exports

@alessiofrittoli/node-scripts
@alessiofrittoli/node-scripts/postinstall
@alessiofrittoli/node-scripts/release
@alessiofrittoli/node-scripts/types

Readme

Node.js Scripts 🫧

Utility library with common Node.js scripts

Getting started
API Reference
- Post-Install scripts
  - TypeScript Type Reference Management
- Release Scripts
  - Release
Development
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 security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli

https://alessiofrittoli.it | info@alessiofrittoli.it

JSPM

@alessiofrittoli/node-scripts

Package Exports

Readme

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`

Using function arguments

Using CLI options

Development

Install depenendencies

Build the source code

ESLint

Jest

Contributing

Security

Made with ☕