Node TypeScript Package Template

@nhz.io/node-ts-package-template

📚 API Documentation

A template repository for Node.js TypeScript packages with test coverage, git hooks, and development tools.

Features

• TypeScript dual module (ESM + CJS)
• Modern ESLint flat config
• Test coverage with c8
• Git hooks with simple-git-hooks
• API documentation with TypeDoc
• CI/CD workflows
• Automated changelog generation with conventional-changelog-cli
• PR labeling
• npm publishing with provenance

Getting Started

1. Click "Use this template" to create a new repository

2. Configure GitHub Actions permissions:

   • Go to repository Settings > Actions > General
   • Under "Workflow permissions":
     • Enable "Read and write permissions"
     • Check "Allow GitHub Actions to create and approve pull requests"

3. Wait for the Template Setup workflow to complete (it runs automatically when repository is created)

4. Configure GitHub Pages:

   • Go to Settings > Pages
   • Select GitHub Actions as the build source

5. Clone your repository

6. Install dependencies:

   npm install
   Copy

Note: After running the template setup workflow:

1. A pull request will be created to update package.json and configure your repository
2. Review and merge this PR to complete the initial setup
3. Once merged, documentation will be automatically deployed when you push changes to main

Scripts

Build

• npm run build - Build ESM and CJS versions
• npm run build:esm - Build ESM version
• npm run build:cjs - Build CJS version
• npm run clean - Remove build artifacts

Development

• npm run dev - Watch mode development
• npm run typecheck - Type checking
• npm run lint - Lint source files
• npm run lint:fix - Fix linting issues
• npm run format - Format files
• npm run format:check - Check formatting

Testing

• npm test - Run tests
• npm run test:coverage - Test with coverage
• npm run test:coverage:check - Check coverage thresholds
• npm run test:coverage:view - View coverage report in browser
• npm run test:coverage:details - Show detailed coverage
• npm run test:coverage:source - Show source-focused coverage
• npm run test:coverage:show - Show coverage with colored source code in terminal
• npm run test:coverage:html - Generate HTML coverage report

Documentation

• npm run docs - Generate documentation
• npm run docs:serve - Serve documentation

Release

• npm run release - Create release (runs patch by default)
• npm run release:major - Major version release
• npm run release:minor - Minor version release
• npm run release:patch - Patch version release

Documentation

The docs directory contains API documentation after running npm run docs.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit changes
4. Push to the branch
5. Create a Pull Request

Release Process

The release process is automated using conventional commits and GitHub Actions. Here's how to create a new release:

1. Create a branch for your changes:

   git checkout -b feat/new-feature  # For features
   git checkout -b fix/bug-fix       # For bug fixes
   Copy

2. Make your changes and commit them using conventional commit messages:

   git commit -m "feat: add new feature"
   git commit -m "fix: fix the bug"
   Copy

3. Create a PR with your changes

4. After your PR is merged to main:

   • Use one of the release scripts to bump version:

     npm run release         # Patch version bump (default)
     npm run release:major   # Major version bump
     npm run release:minor   # Minor version bump
     npm run release:patch   # Patch version bump
     Copy

   • GitHub Actions automatically:
     • Generates the changelog using conventional-changelog-cli
     • Creates a git tag matching the version
     • Creates a GitHub Release
     • Publishes the package to npm with provenance

Publishing

Publishing is fully automated through GitHub Actions.

Requirements:

• Node.js >=20
• npm >=10
• NPM_TOKEN in GitHub repository secrets
• Write permissions for GitHub Actions

License

MIT