diff --git a/README.md b/README.md index f4569102..5174e3e0 100644 --- a/README.md +++ b/README.md @@ -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)