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

| 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

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

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

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

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

• Retrieves CLI options using getProcessOptions().
• Validates critical parameters such as version and access.

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

• Publishes the package using npm publish if the --npm flag is set.

• Restores the stashed changes if any were saved during the process.

• Logs details of the release process if the --verbose flag is set.

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 [email protected] to disclose any security vulnerabilities.

Made with ☕