{"id":45076920,"url":"https://github.com/mxxii/yet-another-typescript-package-template","last_synced_at":"2026-02-19T13:37:20.936Z","repository":{"id":39205619,"uuid":"314893019","full_name":"mxxii/yet-another-typescript-package-template","owner":"mxxii","description":"Template/tools playground for a TypeScript Node library.","archived":false,"fork":false,"pushed_at":"2025-03-17T16:56:25.000Z","size":973,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T17:45:44.433Z","etag":null,"topics":["typescript-boilerplate","typescript-template"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxxii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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}},"created_at":"2020-11-21T19:59:34.000Z","updated_at":"2025-03-17T16:58:48.000Z","dependencies_parsed_at":"2024-12-24T14:12:34.216Z","dependency_job_id":"0d842a00-2fc5-4225-9057-ac3d553d6a46","html_url":"https://github.com/mxxii/yet-another-typescript-package-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/mxxii/yet-another-typescript-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxxii%2Fyet-another-typescript-package-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxxii%2Fyet-another-typescript-package-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxxii%2Fyet-another-typescript-package-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxxii%2Fyet-another-typescript-package-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxxii","download_url":"https://codeload.github.com/mxxii/yet-another-typescript-package-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxxii%2Fyet-another-typescript-package-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29615104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T13:04:20.082Z","status":"ssl_error","status_checked_at":"2026-02-19T13:03:33.775Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["typescript-boilerplate","typescript-template"],"created_at":"2026-02-19T13:37:20.857Z","updated_at":"2026-02-19T13:37:20.925Z","avatar_url":"https://github.com/mxxii.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yet another TypeScript package template\n\n![lint status badge](https://github.com/mxxii/yet-another-typescript-package-template/workflows/lint/badge.svg)\n![test status badge](https://github.com/mxxii/yet-another-typescript-package-template/workflows/test/badge.svg)\n![test coverage badge](https://img.shields.io/nycrc/mxxii/yet-another-typescript-package-template?config=.c8rc.json)\n[![Open in Visual Studio Code](https://img.shields.io/badge/Open_in-Visual_Studio_Code-007acc)](https://open.vscode.dev/mxxii/yet-another-typescript-package-template)\n\nThis template is aimed for Node.js packages development.\n\nIn practice, this is mostly a playground to try out various infrastructure tools.\n\n\n## Package configuration\n\n### Node.js\n\nNode 20 is the target version.\n\n\u003chttps://nodejs.org/en/about/releases/\u003e\n\n### Dual package\n\nUp to date recommendations: \u003chttps://nodejs.org/api/packages.html#packages_dual_commonjs_es_module_packages\u003e\n\nThis template assumes the library is going to be stateless.\n\n### Exports `./package.json`\n\nSome tooling in downstream packages might need this.\n\nSee \u003chttps://github.com/nodejs/node/issues/33460\u003e and \u003chttps://github.com/tsmodule/tsmodule/issues/1\u003e.\n\n\n## TypeScript language\n\n### TSConfig\n\nTSConfig reference: \u003chttps://www.typescriptlang.org/docs/handbook/tsconfig-json.html\u003e\n\nIt is probably a good idea to start new projects with [`--erasableSyntaxOnly`](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) regardless of Node version, so the option is included in `tsconfig.json`. It also ensures compatibility with `ts-blank-space` loader (see below under Testing and benchmarking).\n\n### tsdoc\n\nTSDoc: \u003chttps://tsdoc.org/\u003e\n\nESlint plugin: \u003chttps://tsdoc.org/pages/packages/eslint-plugin-tsdoc/\u003e\n\n### typedoc\n\nGenerate API documentation in the `/docs` folder based on code and TSDoc comments.\n\nTypeDoc: \u003chttps://typedoc.org/\u003e\n\nMarkdown plugin: \u003chttps://github.com/tgreyuk/typedoc-plugin-markdown\u003e (became more powerful in version 4).\n\n### `@arethetypeswrong/cli`\n\nQuirky export resolution algorithms require to provide separate type definition files. This tool helps to validate type exports of a package.\n\nDocs: \u003chttps://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md\u003e\n\nAdditional note: TypeScript export resolution [quirk](https://github.com/microsoft/TypeScript/issues/50762) can cause an issue in complex cases. Can be avoided by keeping `types` implicitly resolvable or defined _before_ `default` export.\n\n\n## Bundling\n\n### rollup\n\n`rollup` bundler allows certain things that [`tsc` CLI](https://www.typescriptlang.org/docs/handbook/compiler-options.html) doesn't, such as more flexible output files naming - this is a must for a dual package.\n\nDocs: \u003chttps://rollupjs.org/guide/en/\u003e\n\nTypeScript support is provided by the official plugin: \u003chttps://github.com/rollup/plugins/tree/master/packages/typescript/#readme\u003e\n\nAlternative TypeScript plugin with some extra features: \u003chttps://github.com/ezolenko/rollup-plugin-typescript2\u003e\n\nType definition files are build with \u003chttps://github.com/Swatinem/rollup-plugin-dts\u003e.\n\nAnother plugin, \u003chttps://github.com/vladshcherbin/rollup-plugin-delete\u003e, might be needed for cleanup of unnecessary generated files.\n\n### pkgroll\n\n\"Zero-configuration\" wrapper around `rollup` and `esbuild` that seems to do just what is needed based on `package.json` alone.\n\nDocs: \u003chttps://github.com/privatenumber/pkgroll\u003e\n\nYet to see how it holds up in more complicated cases. Waits for a PR to update a vulnerable dependency - doesn't instill confidence...\n\n\n## Testing and benchmarking\n\n### ava\n\nMy test framework of choice. Macros and snapshots are pleasure to work with in AVA. Jest often causes various troubles.\n\nTypeScript support via \u003chttps://github.com/bloomberg/ts-blank-space\u003e. It is a type stripper/eraser. Some limitations may apply. Should be perfect with the new `--erasableSyntaxOnly` flag.\n\nIf `ts-blank-space` can't be used, there are \u003chttps://github.com/tapjs/tsimp\u003e (with [known issue](https://github.com/avajs/ava/issues/3349)) and \u003chttps://github.com/TypeStrong/ts-node\u003e (might still work but with own quirks).\n\nMore notes on TypeScript support: \u003chttps://github.com/avajs/ava/blob/master/docs/recipes/typescript.md\u003e\n\n### expect-type\n\n`tsd` is the most known tool for type tests but turns out it is rather opinionated and has some limitations.\n\n\u003chttps://github.com/mmkal/expect-type\u003e seems to be a better alternative.\n\nA common observation about type testing: it is not well compatible with unit testing. The best approach I see is to keep it separate and just run `tsc --noEmit` over it.\n\n### iso-bench\n\n\u003chttps://github.com/Llorx/iso-bench\u003e seems to be a benchmarking library that is most alive and reliable. Benny is simply dead by now and has unresolved issues.\n\n\n## Linting\n\n### eslint\n\nESlint with TypeScript plugin is currently the preferred way to lint `.ts` files.\n\nOnly recommended configs are included with the template, with a minimal set of overrides (same applies to all linting tools).\n\nRules: \u003chttps://eslint.org/docs/rules/\u003e, \u003chttps://eslint.style/rules\u003e and \u003chttps://typescript-eslint.io/rules/\u003e\n\nSeparate `tsconfig.eslint.json` file allows to lint infrastructure files such as tests.\n\nIn order to use `eslint.config.ts` (TypeScript config file) with Node, additional explicit dependency is needed - \u003chttps://github.com/unjs/jiti\u003e. It doesn't seem to function properly as a drop-in replacement of `tsimp` CLI or `ts-blank-space` loader. Moar loaders! hellmo.jpg. No clear advantage to justify extra dependency - it is easier to stick with `eslint.config.(m)js`\n\n`eslint` is a royal PITA to configure. But Prettier is equally extreme approach in opposite direction - 99% opinionated, 1% configurable, no workarounds. So, unable to fight it for simple things, I don't use Prettier and prefer `eslint` with Stylistic.\n\n### eslint-plugin-jsonc\n\nApparently the most solid solution to lint and format JSON files. It reuses ESlint rules where appropriate. Not all defaults play nicely with all configs though, so a couple of overrides is provided.\n\nRules: \u003chttps://ota-meshi.github.io/eslint-plugin-jsonc/rules/\u003e\n\n### markdownlint\n\nRules: \u003chttps://github.com/DavidAnson/markdownlint/blob/main/README.md\u003e\n\n\u003chttps://github.com/DavidAnson/markdownlint-cli2\u003e seems to be a better CLI all around at this point.\n\n\u003chttps://github.com/igorshubovych/markdownlint-cli\u003e followed more conventional approach but is not going to receive future improvements.\n\n### biome\n\nDocs: \u003chttps://biomejs.dev/guides/getting-started/\u003e\n\nTries to replace both `eslint` (linking) and Prettier (formatting), with own analyzer functionality on top (only import sorting for now).\n\nShares the same philosophy and options as Prettier for formatting. This is unfortunate for me. In my own projects, I want code that is readable for me rather than code that is equally crappy for everyone. There are formatting rules that don't exist not because the ideal already exists, but because nobody was at the right place at the right time to formulate something better.\n\nLinter and analyzer still seem like a good value proposition for projects where developers don't want to mess with `eslint` and still get a good set of rules.\n\n\n## Scripts\n\n### `npm-run-all2`\n\n\u003chttps://github.com/bcomnes/npm-run-all2\u003e is a maintained fork of `npm-run-all` tool.\n\n\u003chttps://github.com/open-cli-tools/concurrently\u003e is another alternative, but it seems to not report properly when any of subtasks exited with error.\n\n### onchange\n\nMany tools come with their own watchers, others don't. \u003chttps://github.com/Qard/onchange\u003e seems to be the most straightforward solution to add this feature where it is missing.\n\n\u003chttps://github.com/M-Zuber/npm-watch\u003e might be a suitable alternative in some cases.\n\n\n## GitHub\n\n### GitHub actions\n\n- \u003chttps://docs.github.com/en/free-pro-team@latest/actions/guides/building-and-testing-nodejs\u003e\n- \u003chttps://github.com/actions/setup-node\u003e\n\n### Badges\n\nGitHub workflow status badge: \u003chttps://docs.github.com/en/free-pro-team@latest/actions/managing-workflow-runs/adding-a-workflow-status-badge\u003e\n\n### Coverage\n\nList of coverage providers (among others) supported by Shields_io: \u003chttps://shields.io/badges\u003e\n\n\u003chttps://github.com/bcoe/c8\u003e is used for coverage reports generation. More on c8: \u003chttps://medium.com/the-node-js-collection/rethinking-javascript-test-coverage-5726fb272949\u003e.\n\nInstead of handling coverage reports by a 3rd-party service, a Shields_io badge can be generated based on the minimum required coverage in the config file. See \u003chttps://shields.io/badges/nycrc-config-on-git-hub\u003e (`c8` has compatible config). Obviously, for this to be representative of reality, tests should be run through `c8` with coverage check enabled so that it would fail when conditions aren't met.\n\n### Dependencies\n\n[Depfu](https://depfu.com/) seems to be useful as a display for the state of dependencies. But their \"reasonably up-to-date\" policy - a feature that should make their product more pleasing to use - doesn't seem to work as expected and appears way too \"lazy\".\n\nDependabot is a part of GitHub now, it delivers security updates automatically and can be configured to create regular dependency updates. Among the list of package managers such as npm it also has Github Actions. [Documentation](https://docs.github.com/en/code-security/supply-chain-security/about-dependabot-version-updates).\n\n\u003chttps://github.com/dylang/npm-check\u003e is a handy tool when you need to manage deps manually. It is meant to be installed globally though, so it's only mentioned here.\n\n\u003chttps://marketplace.visualstudio.com/items?itemName=idered.npm\u003e extension for VSCode had a good premise but seems to be dropped half-baked. I only use it now to quickly see the list of available versions for some packages.\n\n\u003chttps://marketplace.visualstudio.com/items?itemName=codeandstuff.package-json-upgrade\u003e extension for VSCode is currently the most helpful tool for me to update dependencies.\n\n\n## License\n\nThis repository is a mere template without own functionality, a configuration for external tools and libraries. And as such, it should not be considered a subject of copyright. Instead, you are encouraged to copy it and apply the license of your choice to the product you build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxxii%2Fyet-another-typescript-package-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxxii%2Fyet-another-typescript-package-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxxii%2Fyet-another-typescript-package-template/lists"}