ts-node-starter

The ts-node-starter scaffolding project is a template repository which makes it easy for you to start a new Node.js project with TypeScript.

Using this template, you can build standalone apps, libraries and/or CLI tools. The ts-node-starter setup is configurable and comes with a lot of features included.

Features

1. Changelog generation powered by generate-changelog
2. Automatic code & config formatting powered by Lefthook
3. Automatic dependency updates powered by Dependabot
4. Config formatting powered by Prettier
5. Code linting powered by ESLint
6. Continuous integration powered by GitHub Actions workflows
7. Dependency management powered by npm
8. Unit testing powered by Vitest
9. Type testing powered by attw
10. Code coverage powered by v8
11. Code coverage reports powered by Codecov
12. Type checking powered by TypeScript
13. Streamlined scripts powered by Conventional Scripts
14. Documentation generation powered by TypeDoc

Usage

Tip

You can use this boilerplate for your own purposes. Just follow the steps below.

By the way, if you like this style, check out other alerts possible with GitHub's Flavored Markdown Spec.

Make it your own

1. Replace all occurrences of "bennycode" with your own username (or organization name)
2. Replace all occurrences of "ts-node-starter" with your project name (or repository name)
3. Delete CHANGELOG.md
4. Delete FUNDING.yml
5. Start writing your code in the "src" directory
6. Run npm install and be happy! 😊

Build a standalone app

Source Code

If you just want to write and run a Node.js app, checkout "src/start.ts".

References

You can start your application by executing yarn start. If you want to debug your code, run yarn debug (Debug Instructions).

Build a Library

Source Code

If you want to distribute your code as a Node.js library on npm, you can have a look at "src/index.ts". If you build a library, I recommend to always ship an index file from where you export the code of your library for others.

References

In the "package.json" file you will also discover a "main" property which defines the entry point to your library when it gets imported by other developers. The value of the "main" property has to point to the transpiled JavaScript code.

Build a CLI

Source Code

If you want to build a CLI tool for Node.js, you can have a look at "src/cli.ts".

References

In the "package.json" file you will also discover a "bin" property which defines the executable name of your tool and the entry point to its transpiled JavaScript code.

If you don't want to publish a CLI, simply remove the "bin" property and the CLI script.

Conventions

Test Files

I recommend to colocate your test code with your source code by naming your test files *.test.ts.

Changelog Generation

The automatic changelog generation is based on Semantic Commit Messages. Simply use the suggested prefixes in your commit messages to make use of it. For example, if you commit a new feature use the "feat" prefix:

Commit Message:

feat: My new feature

If you are introducing a breaking change, add an exclamation mark (!) after the type or scope of your commit message:

Example:

refactoring!: Make file handlers asynchronous

This is as per breaking change definition of Conventional Commits 1.0.0.

Troubleshooting

If you're having trouble with the Git pre-commit hook, then reinstall the hook using the following command:

npx lefthook install --force

Source: Hooks don't run

Updates

The dependencies of this boilerplate are updated regularly. If you prefer to update them yourself, you can also run the following command:

npm update --save

Inspiring Templates

Other inspiring Node.js templates:

• https://github.com/JoshuaKGoldberg/create-typescript-app

Important Refactorings

1. Replaced EditorConfig with Prettier (2e24f7b)
2. Replaced Jasmine with Jest (41e9b42)
3. Replaced action-dependabot-auto-merge with Dependabot & GitHub CLI (86d5696)
4. Replaced husky with Lefthook (9c41615)
5. Replaced custom ESLint Config with a Shareable Config (eef5927)
6. Replaced @types/jest with @jest/globals (73c5bc2)
7. Replaced Yarn 1 with npm (153b726)
8. Replaced pretty-quick with Prettier 3 (7623ba8)
9. Replaced Jest with Vitest (662dddf)
10. Replaced CommonJS with EcmaScript Modules (0cae631)
11. Replaced imports with Vitest Globals (6b273c3)
12. Replaced ts-node with tsimp (5db7e0c)

Contributors