{"id":26477511,"url":"https://github.com/alessiofrittoli/node-scripts","last_synced_at":"2025-03-20T00:47:28.804Z","repository":{"id":283281590,"uuid":"906698520","full_name":"alessiofrittoli/node-scripts","owner":"alessiofrittoli","description":"Utility library with common node.js scripts","archived":false,"fork":false,"pushed_at":"2025-03-19T11:59:49.000Z","size":170,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-19T12:37:16.971Z","etag":null,"topics":["postinstall","postinstall-script","release-automation","shell-scripts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alessiofrittoli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"license.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["alessiofrittoli"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-12-21T16:37:42.000Z","updated_at":"2025-03-19T11:59:52.000Z","dependencies_parsed_at":"2025-03-19T12:48:46.876Z","dependency_job_id":null,"html_url":"https://github.com/alessiofrittoli/node-scripts","commit_stats":null,"previous_names":["alessiofrittoli/node-scripts"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiofrittoli%2Fnode-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiofrittoli%2Fnode-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiofrittoli%2Fnode-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alessiofrittoli%2Fnode-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alessiofrittoli","download_url":"https://codeload.github.com/alessiofrittoli/node-scripts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244530997,"owners_count":20467388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["postinstall","postinstall-script","release-automation","shell-scripts"],"created_at":"2025-03-20T00:47:28.199Z","updated_at":"2025-03-20T00:47:28.788Z","avatar_url":"https://github.com/alessiofrittoli.png","language":"TypeScript","funding_links":["https://github.com/sponsors/alessiofrittoli"],"categories":[],"sub_categories":[],"readme":"# Node.js Scripts 🫧\n\n[![NPM Latest Version][version-badge]][npm-url] [![Coverage Status][coverage-badge]][coverage-url] [![Socket Status][socket-badge]][socket-url] [![NPM Monthly Downloads][downloads-badge]][npm-url] [![Dependencies][deps-badge]][deps-url]\n\n[![GitHub Sponsor][sponsor-badge]][sponsor-url]\n\n[version-badge]: https://img.shields.io/npm/v/%40alessiofrittoli%2Fnode-scripts\n[npm-url]: https://npmjs.org/package/%40alessiofrittoli%2Fnode-scripts\n[coverage-badge]: https://coveralls.io/repos/github/alessiofrittoli/node-scripts/badge.svg\n[coverage-url]: https://coveralls.io/github/alessiofrittoli/node-scripts\n[socket-badge]: https://socket.dev/api/badge/npm/package/@alessiofrittoli/node-scripts\n[socket-url]: https://socket.dev/npm/package/@alessiofrittoli/node-scripts/overview\n[downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Fnode-scripts.svg\n[deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Fnode-scripts\n[deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Fnode-scripts\n\n[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23DB61A2\n[sponsor-url]: https://github.com/sponsors/alessiofrittoli\n\n## Utility library with common Node.js scripts\n\n### Table of Contents\n\n- [Getting started](#getting-started)\n- [API Reference](#api-reference)\n  - [Post-Install scripts](#post-install-scripts)\n    - [TypeScript Type Reference Management](#typescript-type-reference-management)\n      - [Type Reference Interfaces](#type-reference-interfaces)\n        - [`CommonOptions`](#commonoptions)\n        - [`AddTypesReferenceOptions`](#addtypesreferenceoptions)\n      - [Type Reference Functions](#type-reference-functions)\n        - [`createReferenceFile`](#createreferencefile)\n        - [`updateTsConfig`](#updatetsconfig)\n        - [`addTypesReference`](#addtypesreference)\n      - [Add Types Reference Example usage](#add-types-reference-example-usage)\n  - [Publish Scripts](#publish-scripts)\n    - [Publish](#publish)\n- [Development](#development)\n  - [Install depenendencies](#install-depenendencies)\n  - [Build the source code](#build-the-source-code)\n  - [ESLint](#eslint)\n  - [Jest](#jest)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Credits](#made-with-)\n\n---\n\n### Getting started\n\nRun the following command to start using `node-scripts` in your projects:\n\n```bash\nnpm i @alessiofrittoli/node-scripts\n```\n\nor using `pnpm`\n\n```bash\npnpm i @alessiofrittoli/node-scripts\n```\n\n---\n\n### API Reference\n\n#### Post-Install scripts\n\n##### TypeScript Type Reference Management\n\nThe `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.\n\nBelow are the detailed descriptions of the interfaces and functions included.\n\n###### Type Reference Interfaces\n\n###### `CommonOptions`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eProperties\u003c/summary\u003e\n\n| Property     | Type     | Description |\n|--------------|----------|-------------|\n| `root`       | `string` | The root directory of the project which is installing your node module. |\n| `name`       | `string` | The name of your node module. |\n| `outputFile` | `string` | The output file name. |\n\n\u003c/details\u003e\n\n---\n\n###### `AddTypesReferenceOptions`\n\n\u003cdetails\u003e\n\n\u003csummary\u003eProperties\u003c/summary\u003e\n\n| Property     | Type     | Default | Description |\n|--------------|----------|---------|-------------|\n| `name`       | `string` | - | The project name currently executing the script. |\n| `outputFile` | `string` | 'alessiofrittoli-env.d.ts' | The *.d.ts output file name. |\n\n\u003c/details\u003e\n\n---\n\n###### Type Reference Functions\n\n###### `createReferenceFile`\n\nCreates or updates a reference file with type definitions for a project.\n\n\u003cdetails\u003e\n\n**Parameters**\n\n| Parameter    | Type            | Description |\n|--------------|-----------------|-------------|\n| `options`    | `CommonOptions` | Common options for the reference file creation. |\n\n- See [CommonOptions](#commonoptions) interface.\n\n**Returns**\n\n`void`\n\n**Throws**\n\n`Error` - Throws an error if there is an issue creating or updating the file.\n\n\u003c/details\u003e\n\n###### `updateTsConfig`\n\nUpdates the tsconfig.json file by adding the specified output file to the `include` array.\n\n\u003cdetails\u003e\n\n**Parameters**\n\n| Parameter    | Type            | Description |\n|--------------|-----------------|-------------|\n| `options`    | `CommonOptions` | Common options for the reference file creation. |\n\n- See [CommonOptions](#commonoptions) interface.\n\n**Returns**\n\n`void`\n\n**Throws**\n\n`Error` - Throws an error if the tsconfig.json file cannot be read or updated.\n\n\u003c/details\u003e\n\n###### `addTypesReference`\n\nAdds a TypeScript reference file and updates the tsconfig.json for the project installing your node module.\n\nIf the `options.outputFile` already exists, it will be updated with the new package reference if not already in there.\n\n\u003cdetails\u003e\n\n**Parameters**\n\n| Parameter    | Type            | Description |\n|--------------|-----------------|-------------|\n| `options`    | `AddTypesReferenceOptions` | The options for adding the types reference. |\n\n- See [AddTypesReferenceOptions](#addtypesreferenceoptions) interface.\n\n**Returns**\n\n`void`\n\n**Error**\n\nExit the process with code `1` on failure.\n\n\u003c/details\u003e\n\n---\n\n###### Add Types Reference Example usage\n\n\u003cdetails\u003e\n\nAdd the `postinstall` script in your `package.json` file which will execute the script once your package get installed in an external project.\n\n```json\n{\n    // ...\n    \"files\": [\n        // ...,\n        \"path-to-my-scripts\" // ensure folder is published to `npm`\n    ],\n    \"scripts\": {\n        // ...\n        \"postinstall\": \"node path-to-my-scripts/ts-setup.js\"\n    }\n}\n```\n\nThen in your `ts-setup.js` file simply import the script and execute it with a few options.\n\n```ts\n// path-to-my-scripts/ts-setup.js\nconst { addTypesReference } = require( '@alessiofrittoli/node-scripts/postinstall' )\nconst project = require( '../../package.json' )\n\naddTypesReference( {\n    name: project.name,\n    outputFile: `${ project.name }.d.ts`, // optional\n} )\n```\n\nOr you can statically pass a `outputFile` to add all your scoped packages in a single file.\n\n```ts\n// path-to-my-scripts/ts-setup.js\nconst { addTypesReference } = require( '@alessiofrittoli/node-scripts/postinstall' )\nconst project = require( '../../package.json' )\n\naddTypesReference( {\n    name: project.name,\n    outputFile: 'my-package-scope-env.d.ts',\n} )\n```\n\n\u003c/details\u003e\n\n---\n\n#### Publish scripts\n\n##### `publish`\n\nThe `publish` function automates the process of building, tagging, and optionally publishing a project to npm.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eProcess Options\u003c/summary\u003e\n\n| Option           | Type                   | Default                 | Description |\n|------------------|------------------------|-------------------------|-------------|\n| `--version`      | `string`               | Value from package.json | The version to release. Retrieved from package.json if omitted. |\n| `--verbose`      | `boolean \\| undefined` | `false`                 | Enables detailed logging. |\n| `--origin`, `-o` | `string`               | 'origin'                | The Git origin for pushing tags. |\n| `--npm`          | `boolean \\| undefined` | `false`                 | Indicates whether to publish the package to npm. |\n| `--access`       | `public \\| restricted` | 'public'                | Sets npm access level (public or restricted). |\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003ePerformed steps\u003c/summary\u003e\n\n\u003col\u003e\n\u003cli\u003e\nRetrieve package.json:\n\n- Attempts to load and parse the `package.json` file.\n- Exits the process with code \"1\" if the file is unavailable or invalid.\n- Retrieve the version to use as fallback if no `--version` option has been provided.\n\n\u003c/li\u003e\n\u003cli\u003e\nParse Options:\n\n- Retrieves CLI options using `getProcessOptions()`.\n- Validates critical parameters such as `version` and `access`.\n\n\u003c/li\u003e\n\u003cli\u003e\nPrepare Git and Build:\n\n- Stashes any uncommitted changes with a stash name (`pre-release`).\n- Executes the `npm run build` or `pnpm build` command (if `pnpm` is globally installed).\n- Create the Git Tag as `v{version}`\n- Push the Git Tag the the specified `origin` or to the default Git Repository Remote.\n\n\u003c/li\u003e\n\u003cli\u003e\nPublish to npm (Optional):\n\n- Publishes the package using `npm publish` if the `--npm` flag is set.\n\n\u003c/li\u003e\n\u003cli\u003e\nRestore Stash:\n\n- Restores the stashed changes if any were saved during the process.\n\n\u003c/li\u003e\n\u003cli\u003e\nVerbose Logging:\n\n- Logs details of the publish process if the `--verbose` flag is set.\n\n\u003c/li\u003e\n\u003c/ol\u003e\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003eExample usage\u003c/summary\u003e\n\nAdd the `release` script in your `package.json` file so you can easly run from your terminal.\n\n```json\n{\n    // ...\n    \"scripts\": {\n        // ...\n        \"release\": \"node path-to-my-scripts/publish.js --verbose --npm --access restricted\"\n    }\n}\n```\n\nThen in your `publish.js` file simply import the script and execute it.\n\n⚠️ Remember to add this file to `.npmignore` so it won't be published within you package.\n\n```ts\n// path-to-my-scripts/publish.js\nrequire( '@alessiofrittoli/node-scripts/publish' )\n    .publish()\n```\n\n\u003c/details\u003e\n\n---\n\n### Development\n\n#### Install depenendencies\n\n```bash\nnpm install\n```\n\nor using `pnpm`\n\n```bash\npnpm i\n```\n\n#### Build the source code\n\nRun the following command to test and build code for distribution.\n\n```bash\npnpm build\n```\n\n#### [ESLint](https://www.npmjs.com/package/eslint)\n\nwarnings / errors check.\n\n```bash\npnpm lint\n```\n\n#### [Jest](https://npmjs.com/package/jest)\n\nRun all the defined test suites by running the following:\n\n```bash\n# Run tests and watch file changes.\npnpm test:watch\n\n# Run tests and watch file changes with jest-environment-jsdom.\npnpm test:jsdom\n\n# Run tests in a CI environment.\npnpm test:ci\n\n# Run tests in a CI environment with jest-environment-jsdom.\npnpm test:ci:jsdom\n```\n\nYou can eventually run specific suits like so:\n\n```bash\npnpm test:jest\npnpm test:jest:jsdom\n```\n\nRun tests with coverage.\n\nAn HTTP server is then started to serve coverage files from `./coverage` folder.\n\n⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.\n\n```bash\ntest:coverage:serve\n```\n\n---\n\n### Contributing\n\nContributions are truly welcome!\n\nPlease refer to the [Contributing Doc](./CONTRIBUTING.md) for more information on how to start contributing to this project.\n\nHelp keep this project up to date with [GitHub Sponsor][sponsor-url].\n\n[![GitHubSponsor][sponsor-badge]][sponsor-url]\n\n---\n\n### Security\n\nIf 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.\n\n### Made with ☕\n\n\u003ctable style='display:flex;gap:20px;'\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\n        \u003cimg alt=\"avatar\" src='https://avatars.githubusercontent.com/u/35973186' style='width:60px;border-radius:50%;object-fit:contain;'\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n        \u003ctable style='display:flex;gap:2px;flex-direction:column;'\u003e\n          \u003ctbody\u003e\n              \u003ctr\u003e\n                \u003ctd\u003e\n                  \u003ca href='https://github.com/alessiofrittoli' target='_blank' rel='noopener'\u003eAlessio Frittoli\u003c/a\u003e\n                \u003c/td\u003e\n              \u003c/tr\u003e\n              \u003ctr\u003e\n                \u003ctd\u003e\n                  \u003csmall\u003e\n                    \u003ca href='https://alessiofrittoli.it' target='_blank' rel='noopener'\u003ehttps://alessiofrittoli.it\u003c/a\u003e |\n                    \u003ca href='mailto:info@alessiofrittoli.it' target='_blank' rel='noopener'\u003einfo@alessiofrittoli.it\u003c/a\u003e\n                  \u003c/small\u003e\n                \u003c/td\u003e\n              \u003c/tr\u003e\n          \u003c/tbody\u003e\n        \u003c/table\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falessiofrittoli%2Fnode-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falessiofrittoli%2Fnode-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falessiofrittoli%2Fnode-scripts/lists"}