Skip to content

Update README to improve clarity #1087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
threeal merged 1 commit into from
May 18, 2026
Merged

Update README to improve clarity #1087

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 34 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,36 @@
# Node.js Starter

A minimalistic template for starting a new [Node.js](https://nodejs.org/en) project.

This template provides a basic Node.js project containing a sample library written in [TypeScript](https://www.typescriptlang.org/), with support for formatting, linting, testing, and continuous integration.

## Key Features

- Minimal Node.js project written in TypeScript with [ESM](https://nodejs.org/api/esm.html) support.
- Uses [pnpm](https://pnpm.io/) as the package manager.
- Supports formatting with [Prettier](https://prettier.io/), linting with [ESLint](https://eslint.org/), and testing with [Vitest](https://vitest.dev/).
- Fixes formatting and linting during pre-commit hooks using [Lefthook](https://lefthook.dev/).
- Preconfigured [Dependabot](https://docs.github.com/en/code-security/dependabot) and [GitHub Actions](https://github.com/features/actions) workflows that validate the pre-commit hook.

## Usage

This guide explains how to use this template to start a new Node.js project, from creation to release.

### Create a New Project

Follow [this link](https://github.com/new?template_name=nodejs-starter&template_owner=threeal) to create a new project based on this template. For more information about creating a repository from a template on GitHub, refer to [this documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).

Alternatively, you can also clone this repository locally to begin using this template.

### Choose a License

By default, this template is [unlicensed](https://unlicense.org/). Before modifying this template, it is recommended to replace the [`LICENSE`](./LICENSE) file with the license that will be used by the new project. For more information about licensing a repository, refer to [this documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository).

Alternatively, you can remove the `LICENSE` file or leave it as is to keep the new project unlicensed.

### Update Project Information

To replace the sample information in this template with your new project information, complete the following steps:

- Replace the content of this [`README.md`](./README.md) file with a description of the new project. For more information on adding READMEs to a project, refer to [this documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes).
- Update project information in the [`package.json`](./package.json) file. For more details on the `package.json` schema, refer to [this documentation](https://docs.npmjs.com/cli/v10/configuring-npm/package-json).

### Set Up Tools

This template uses [pnpm](https://pnpm.io/) as the package manager. If pnpm is not installed, follow [this guide](https://pnpm.io/installation) to install it. Then, install the project dependencies with:

```sh
pnpm install
```

For more information on pnpm, including adding dependencies or running tools, refer to [this documentation](https://pnpm.io/pnpm-cli).

This template also uses [Lefthook](https://lefthook.dev/) to manage Git hooks. Lefthook is an external tool that must be installed independently — refer to [this guide](https://lefthook.dev/installation/) for installation instructions. Once installed, set up the Git hooks with:

```sh
lefthook install
```

### Developing the Library

This template provides two components: the library itself ([`src/lib.ts`](./src/lib.ts)) and an executable entry point ([`src/bin.ts`](./src/bin.ts)). Write code according to your project requirements. If you're new to [TypeScript](https://www.typescriptlang.org/), refer to [this documentation](https://www.typescriptlang.org/docs/) for guidance.

If your project doesn’t need an executable, you can remove `src/bin.ts` and the `bin` entry from the [`package.json`](./package.json) file.

### Testing the Library

Test files in this template are named `*.test.ts` and typically correspond to the source files being tested. This template uses [Vitest](https://vitest.dev/) as the testing framework. For more information on testing with Vitest, refer to [this documentation](https://vitest.dev/guide/).

After creating your test files, run tests with:

```sh
pnpm test
```

### Release the Library

When the project is complete, package the library by running:

```sh
pnpm pack
```

This will create a tarball file, which can be included in the release. Ensure the project is at the correct version and has been pushed to the upstream repository. For more information on releasing a project, refer to [this documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases).
A minimal [Node.js](https://nodejs.org/en) project template written in [TypeScript](https://www.typescriptlang.org/), with formatting, linting, testing, and CI/CD ready to go.

## What's Included

- **TypeScript** library with [ESM](https://nodejs.org/api/esm.html) support and a CLI entry point using [Commander.js](https://github.com/tj/commander.js)
- **[pnpm](https://pnpm.io/)** as the package manager
- **Formatting** with [Prettier](https://prettier.io/) and **linting** with [ESLint](https://eslint.org/)
- **Testing** with [Vitest](https://vitest.dev/) — 100% code coverage required
- **Pre-commit hooks** with [Lefthook](https://lefthook.dev/) — auto-formats and lints before each commit
- **Dependabot** — keeps GitHub Actions and npm dependencies up to date automatically
- **CI workflow** — validates the pre-commit hook on every pull request and push to `main`

## Getting Started

1. [Create a new repository](https://github.com/new?template_name=nodejs-starter&template_owner=threeal) from this template, or clone it directly.
2. Install [pnpm](https://pnpm.io/installation) and run `pnpm install` to set up project dependencies.
3. Install [Lefthook](https://lefthook.dev/installation/) and run `lefthook install` to activate the pre-commit hook.
4. Replace the [`LICENSE`](./LICENSE) file with your preferred license, or keep it to keep the project [unlicensed](https://unlicense.org/).
5. Modify the template files to fit your project.

## Customizing

Each file is a starting point — modify it to fit your needs:

- `src/lib.ts` — replace the placeholder library with your own implementation
- `src/bin.ts` — replace the placeholder CLI, or remove it along with the `bin` entry in `package.json` if not needed
- `package.json` — update project name, description, version, and other metadata
- `.prettierrc.json` — adjust formatting options
- `eslint.config.ts` — adjust linting rules
- `vitest.config.ts` — adjust test configuration and coverage thresholds
- `lefthook.yaml` — add more pre-commit checks or other Git hooks
- `.github/workflows/ci.yaml` — extend or replace the CI workflow
- `.github/dependabot.yaml` — adjust update frequency or add more package ecosystems
- `CLAUDE.md` — replace with guidance for your project's structure, tools, and development workflow (for Claude Code)
Loading