Node.js Scripts 🫧

Utility library with common Node.js scripts

Table of Content

• Getting started
• Development
  • Local development
  • Production build
  • Unit tests
    • Run tests with coverage
  • Contributing
  • Security
• API Reference
  • Post-Install scripts
    • TypeScript Type Reference Management
      • Type Reference Interfaces
        • CommonOptions
        • AddTypesReferenceOptions
      • Type Reference Functions
        • createReferenceFile
        • updateTsConfig
        • addTypesReference
  • Release Scripts
    • Release
• 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

---

Development

Run the following to start development

nvm use

pnpm i

Local development

Run the following

pnpm dev

This will generate unminified output code, sourcemaps and will enable source file watcher.

---

Production build

Run the following to create a local production build

pnpm build

This will generate minified output code without sourcemaps.

---

Unit tests

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

---

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.

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

---

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.
scopes	string[]	-	An array of scopes references used over package name.
outputFile	string	'globals.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.

---

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.

---

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.

---

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": [
    // ...,
    "my-scripts" // ensure folder is published to `npm`
  ],
  "scripts": {
    // ...
    "postinstall": "node my-scripts/ts-setup.ts"
  }
}

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

// my-scripts/ts-setup.ts
import { addTypesReference } from '@alessiofrittoli/node-scripts/postinstall'
import packageJson from '../package.json'

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

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

// my-scripts/ts-setup.ts
import { addTypesReference } from '@alessiofrittoli/node-scripts/postinstall'
import packageJson from '../package.json'

addTypesReference({
  name: packageJson.name,
  outputFile: 'my-package-scope-env.d.ts',
})

---

Add custom types references

// my-scripts/ts-setup.ts
import { addTypesReference } from '@alessiofrittoli/node-scripts/postinstall'
import packageJson from '../package.json'

addTypesReference({
  name: packageJson.name,
  types: [`${packageJson.name}/globals`, `${packageJson.name}/globals-2`],
  outputFile: `${packageJson.name}.d.ts`, // optional
})

---

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

1. 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.
2. Parse Options:
   • Retrieves CLI options using getProcessOptions().
   • Validates critical parameters such as version and access.
3. 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.
4. Publish to npm (Optional):
   • Publishes the package using npm publish if the --npm flag is set.
5. Restore Stash:
   • Restores the stashed changes if any were saved during the process.
6. 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 my-scripts/release.ts"
  }
}

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

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

// my-scripts/release.ts
import { release } from '@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 my-scripts/release.ts --verbose --npm --access restricted"
  }
}

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

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

// my-scripts/release.ts
import { release } from '@alessiofrittoli/node-scripts/release'

release()

---

Made with ☕

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