Explainer

This template is available for anybody who wants to set up a basic Node application using TypeScript. It sets up the following tooling for you:

• All Contributors: Tracks various kinds of contributions and displays them in a nicely formatted table in the README.md.
• ESLint: Static analysis for JavaScript code, configured with typescript-eslint for TypeScript code and other general-use plugins.
• Knip: Detects unused files, dependencies, and code exports.
• Markdownlint: Static analysis for Markdown code.
• pnpm: Disk-efficient package manager alternative.
• PR Compliance Action: Checks PRs for compliance such as addressing a linked issue and proper title formatting.
• Prettier: Opinionated formatting for code, run on file save and as a Git commit hook via husky and lint-staged.
• release-it: Generates changelogs, bumps the package version, and publishes to GitHub and npm based on conventional commits.
• Renovate: Keeps dependencies up-to-date with PRs, configured to wait a few days after each update for safety.
• TypeScript: A typed superset of JavaScript, configured with strict compiler options.
• Vitest: Fast unit tests, configured with coverage tracking and console-fail-test.

Setup

This package comes with a bootstrap/initialization setup script that fills out your repository's details, installs necessary packages, then removes itself and uninstalls setup dependencies.

First make sure you have the following installed:

• GitHub CLI (you'll need to be logged in)
• Node.js
• pnpm

To use this template:

1. Click the Use this template button to create a new repository with the same Git history
2. Open that repository, such as by cloning it locally or developing in a codespace
3. Create two tokens in repository secrets:
   • ACCESS_TOKEN: A GitHub PAT with repo and workflow permissions
   • NPM_TOKEN: An npm access token with Automation permissions
4. pnpm install
5. pnpm run setup to run the setup script
6. Install the Codecov GitHub App and Renovate GitHub App

The setup script removes the ## Explainer, ## Setup, and ## Repository Hydration sections from this README.md.

Setup Options

The setup script requires four options to fill out repository details. It will interactively prompt for any that are not provided as a string CLI flag:

1. repository: The kebab-case name of the repository (e.g. template-typescript-node-package)
2. title: Title Case title for the repository to be used in documentation (e.g. Template TypeScript Node Package)
3. owner: GitHub organization or user the repository is underneath (e.g. JoshuaKGoldberg)
4. description: Sentence case description of the repository (e.g. A quickstart-friendly TypeScript package with lots of great repository tooling. ✨)

Additionally, a --skip-api boolean CLI flag may be specified to prevent the setup script from calling to GitHub APIs for repository hydration. The script normally posts to GitHub APIs to set information such as repository description and branch protections on github.com. Specifying --skip-api prevents those API calls, effectively limiting setup changes to local files in Git. Doing so can be useful to preview what running setup does.

For example, pre-populating all values and skipping API calls:

pnpm run setup --repository "testing-repository" --title "Testing Title" --owner "TestingOwner" --description "Test Description" --skip-api

Tip: after running pnpm run setup with --skip-api, you can always git add -A; git reset --hard HEAD to completely reset all changes.

Repository Hydration

Warning Hydration will override many files in your repository. You'll want to review each of the changes and make sure nothing important is removed.

Alternately, if you have an existing repository that you'd like to give the files from this repository, you can run template-typescript-node-package in a repository to "hydrate" it.

npx template-typescript-node-package

Repository settings will be auto-filled from the repository's files if possible, but can be provided manually as well:

• author (string): e.g. "Josh Goldberg"
• description (string): e.g. "A quickstart-friendly TypeScript template with comprehensive formatting, linting, releases, testing, and other great tooling built-in. ✨"
• email (string): e.g. "[email protected]"
• funding (string, optional): e.g. "JoshuaKGoldberg"
• owner (string): e.g. "JoshuaKGoldberg"
• repository (string): e.g. "template-typescript-node-package"
• title (string): e.g. "Template TypeScript Node Package"

For example, providing a funding value different from the author:

npx template-typescript-node-package --funding MyOrganization

The hydration script by default will include all the features in this template. You can disable some of them on the command-line:

• releases (boolean): Whether to include automated package publishing
• unitTests (boolean): Whether to include unit tests with code coverage tracking

npx template-typescript-node-package --releases false --unitTests false

You can prevent the hydration script from making network-based changes using either or both of the following CLI flags:

• --skip-install (boolean): Skips installing all the new template packages with pnpm
• --skip-setup (boolean): Skips running the setup script at the end of hydration

npx template-typescript-node-package --skip-install --skip-setup

Usage

npm i template-typescript-node-package

import { greet } from "template-typescript-node-package";

greet("Hello, world!");

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

Contributors