@alessiofrittoli/node-scripts v2.6.0

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
  • Publish Scripts
    • Publish
• 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

AddTypesReferenceOptions

Type Reference Functions

createReferenceFile

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

Parameters

• 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

• 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

• 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',
} )

Publish scripts

publish

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

• 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 publish process if the --verbose flag is set.

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

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

Then in your publish.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/publish.js
require( '@alessiofrittoli/node-scripts/publish' )
    .publish()

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 ☕