https://github.com/mxxii/yet-another-typescript-package-template
Template/tools playground for a TypeScript Node library.
https://github.com/mxxii/yet-another-typescript-package-template
typescript-boilerplate typescript-template
Last synced: 4 months ago
JSON representation
Template/tools playground for a TypeScript Node library.
- Host: GitHub
- URL: https://github.com/mxxii/yet-another-typescript-package-template
- Owner: mxxii
- Created: 2020-11-21T19:59:34.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-17T16:56:25.000Z (over 1 year ago)
- Last Synced: 2025-03-17T17:45:44.433Z (over 1 year ago)
- Topics: typescript-boilerplate, typescript-template
- Language: JavaScript
- Homepage:
- Size: 950 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Yet another TypeScript package template
[](https://open.vscode.dev/mxxii/yet-another-typescript-package-template)
This template is aimed for Node.js packages development.
In practice, this is mostly a playground to try out various infrastructure tools.
## Package configuration
### Node.js
Node 20 is the target version.
### Dual package
Up to date recommendations:
This template assumes the library is going to be stateless.
### Exports `./package.json`
Some tooling in downstream packages might need this.
See and .
## TypeScript language
### TSConfig
TSConfig reference:
It 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).
### tsdoc
TSDoc:
ESlint plugin:
### typedoc
Generate API documentation in the `/docs` folder based on code and TSDoc comments.
TypeDoc:
Markdown plugin: (became more powerful in version 4).
### `@arethetypeswrong/cli`
Quirky export resolution algorithms require to provide separate type definition files. This tool helps to validate type exports of a package.
Docs:
Additional 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.
## Bundling
### rollup
`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.
Docs:
TypeScript support is provided by the official plugin:
Alternative TypeScript plugin with some extra features:
Type definition files are build with .
Another plugin, , might be needed for cleanup of unnecessary generated files.
### pkgroll
"Zero-configuration" wrapper around `rollup` and `esbuild` that seems to do just what is needed based on `package.json` alone.
Docs:
Yet to see how it holds up in more complicated cases. Waits for a PR to update a vulnerable dependency - doesn't instill confidence...
## Testing and benchmarking
### ava
My test framework of choice. Macros and snapshots are pleasure to work with in AVA. Jest often causes various troubles.
TypeScript support via . It is a type stripper/eraser. Some limitations may apply. Should be perfect with the new `--erasableSyntaxOnly` flag.
If `ts-blank-space` can't be used, there are (with [known issue](https://github.com/avajs/ava/issues/3349)) and (might still work but with own quirks).
More notes on TypeScript support:
### expect-type
`tsd` is the most known tool for type tests but turns out it is rather opinionated and has some limitations.
seems to be a better alternative.
A 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.
### iso-bench
seems to be a benchmarking library that is most alive and reliable. Benny is simply dead by now and has unresolved issues.
## Linting
### eslint
ESlint with TypeScript plugin is currently the preferred way to lint `.ts` files.
Only recommended configs are included with the template, with a minimal set of overrides (same applies to all linting tools).
Rules: , and
Separate `tsconfig.eslint.json` file allows to lint infrastructure files such as tests.
In order to use `eslint.config.ts` (TypeScript config file) with Node, additional explicit dependency is needed - . 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`
`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.
### eslint-plugin-jsonc
Apparently 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.
Rules:
### markdownlint
Rules:
seems to be a better CLI all around at this point.
followed more conventional approach but is not going to receive future improvements.
### biome
Docs:
Tries to replace both `eslint` (linking) and Prettier (formatting), with own analyzer functionality on top (only import sorting for now).
Shares 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.
Linter 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.
## Scripts
### `npm-run-all2`
is a maintained fork of `npm-run-all` tool.
is another alternative, but it seems to not report properly when any of subtasks exited with error.
### onchange
Many tools come with their own watchers, others don't. seems to be the most straightforward solution to add this feature where it is missing.
might be a suitable alternative in some cases.
## GitHub
### GitHub actions
-
-
### Badges
GitHub workflow status badge:
### Coverage
List of coverage providers (among others) supported by Shields_io:
is used for coverage reports generation. More on c8: .
Instead 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 (`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.
### Dependencies
[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".
Dependabot 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).
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.
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.
extension for VSCode is currently the most helpful tool for me to update dependencies.
## License
This 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.