{"id":14156101,"url":"https://github.com/npm/template-oss","last_synced_at":"2025-04-05T06:02:14.576Z","repository":{"id":40385294,"uuid":"400593879","full_name":"npm/template-oss","owner":"npm","description":"a template package for npm CLI team development","archived":false,"fork":false,"pushed_at":"2025-03-05T20:48:07.000Z","size":22793,"stargazers_count":31,"open_issues_count":12,"forks_count":20,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-29T05:01:45.293Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-27T17:56:37.000Z","updated_at":"2025-03-18T06:16:14.000Z","dependencies_parsed_at":"2023-01-23T18:30:45.928Z","dependency_job_id":"2c849ea9-32cc-462d-8c81-4d3acdd8323b","html_url":"https://github.com/npm/template-oss","commit_stats":{"total_commits":284,"total_committers":9,"mean_commits":"31.555555555555557","dds":0.6091549295774648,"last_synced_commit":"1babe54a8db71b40cf0eaabf3ee056796ba333ae"},"previous_names":[],"tags_count":100,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Ftemplate-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Ftemplate-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Ftemplate-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Ftemplate-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/template-oss/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294513,"owners_count":20915340,"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":["npm-cli"],"created_at":"2024-08-17T08:05:13.164Z","updated_at":"2025-04-05T06:02:14.543Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"## @npmcli/template-oss\n\nThis module bundles the npm CLI team's basics for package development into a\nsingle devDependency.\n\n\u003e [!WARNING]  \n\u003e THESE CHANGES WILL OVERWRITE LOCAL FILES AND SETTINGS\n\n\u003e [!IMPORTANT]  \n\u003e This package does not follow semantic versioning for its API. This package is designed to be installed with `--save-exact` and therefore will make breaking API changes outside of major versions, including `engines` narrowing. Major versions are reserved for breaking changes to files written to a repo by this package.\n\n### Configuration\n\nConfigure the use of `@npmcli/template-oss` in your `package.json` using the\n`templateOSS` property.\n\n\n```js\n{\n  name: 'my-package',\n  templateOSS: {\n    // copy repo specific files for the root pkg\n    rootRepo: true,\n    // modify package.json and copy module specific files for the root pkg\n    rootModule: true,\n    // copy repo files for all workspaces\n    workspaceRepo: true,\n    // copy module files for all workspaces\n    workspaceModule: true,\n    // filter allowed workspaces by package name\n    // defaults to all workspaces\n    workspaces: ['workspace-package-name'],\n    // The rest of the config is passed in as variables\n    // that can be used to template files in the content\n    // directory. Some common ones are:\n    // Turns off ci in windows\n    windowsCI: false,\n    // Change the versions tested in CI and engines\n    ciVersions: ['10', '12', '14']\n  }\n}\n```\n\n#### Workspaces\n\nIndividual workspaces can also supply their own config, if they are included by\nthe root package's `templateOSS.workspaces` array. These settings will override\nany of the same settings in the root.\n\n```js\n{\n  name: 'my-workspace',\n  templateOSS: {\n    // copy repo files for this workspace\n    workspaceRepo: true,\n    // copy module files for this workspace\n    moduleRepo: true,\n    // Changes windowsCI setting for this workspace\n    windowsCI: false,\n  }\n}\n```\n\n### Content\n\nAll the templated content for this repo lives in\n[`lib/content/`](./lib/content/). The [`index.js`](./lib/content/index.js) file\ncontrols how and where this content is written.\n\nContent files can be overwritten or merged with the existing target file.\nMerging is only supported for some types of files (ini, yaml, json, package.json)\n\nEach content file goes through the following pipeline:\n\n1. It is read from its source location\n2. It is compiled using [Handlebars](https://handlebarsjs.com/) with the variables from each packages's\n   config (with some derived values generated in [`config.js`](./lib/config.js))\n3. It is parsed based on its file extension in\n   [`parser.js`](./lib/util/parser.js)\n4. Additional logic is applied by the parser\n5. It is written to its target location\n\n### Usage\n\nThis package provides two bin scripts:\n\n#### `template-oss-check`\n\nThis will check if any of the applied files differ from the target content,\nor if any of the other associated checks fail. The diffs of each file or check\nwill be reported with instructions on how to fix it.\n\n#### `template-oss-apply [--force]`\n\nThis will write all source files to their target locations in the cwd. It will\ndo nothing if `package.json#templateOSS.version` is the same as the version\nbeing run. This can be overridden by `--force`.\n\nThis is the script that is run on `postinstall`.\n\n### Extending\n\n#### `lib/apply`\n\nThis directory is where all the logic for applying files lives. It should be\npossible to add new files without modifying anything in this directory. To add a\nfile, add the templated file to `lib/content/$FILENAME` and an entry for it in\n`lib/content/index.js` depending on where and when it should be written (root vs\nworkspace, repo vs module, add vs remove, etc).\n\n#### `lib/check`\n\nAll checks live in this directory and have the same signature. A check must be\nadded to `lib/check/index.js` for it to be run.\n\n#### Generic vs specific extensions\n\nThis repo is designed so that all (fine, most) of the logic in `lib/` is generic\nand could be applied across projects of many different types.\n\nThe files in `lib/content` are extremely specific to the npm CLI. It would be\ntrivial to swap out this content directory for a different one as it is only\nreferenced in a single place in `lib/config.js`. However, it's not currently\npossible to change this value at runtime, but that might become possible in\nfuture versions of this package.\n\n### Testing\n\nThe files `test/release/release-manager.js` and `test/release/release-please.js`\nuse recorded `nock` fixtures to generate snapshots. To update these fixtures run:\n\n```sh\nGITHUB_TOKEN=$(gh auth token) npm run test:record --- test/release/release-{please,manager}.js\n```\n\nIf you only need to update fixtures for one, it's best to only run that single\ntest file.\n\n#### `test/release/release-please.js`\n\nThis test file uses the repo `npm/npm-cli-release-please` to record its\nfixtures. It expects `https://github.com/npm/npm-cli-release-please` to be\nchecked out in a sibling directory to this repo. It also needs the current\nbranch set to `template-oss-mock-testing-branch-do-not-delete` before the tests\nare run.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Ftemplate-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Ftemplate-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Ftemplate-oss/lists"}