TypeScript Package Starter

A modern, well-configured starter template for creating TypeScript npm packages. This template provides a solid foundation with best practices and essential tooling for TypeScript package development.

Features

• 📦 Modern build setup with tsup
• 🔥 ESM and CommonJS support
• 📘 TypeScript with strict mode
• 🧪 Testing with Jest
• 📊 Code coverage reporting
• 📝 API documentation with TypeDoc
• ✨ Code formatting with Prettier
• 🚨 Linting with ESLint
• 🔄 Continuous Integration with GitHub Actions
• 📋 Conventional commits with commitlint
• 🪝 Git hooks with husky
• 🌲 Tree-shakeable exports
• 📦 Optimized npm package exports
• 🤖 Automated dependency updates with Renovate

Getting Started

1. Use this template by clicking the "Use this template" button on GitHub or clone it directly:

git clone https://github.com/imgarylai/ts-package-starter.git my-package
cd my-package

2. Update the package information:

   • Modify package.json with your package name, description, author, etc.
   • Update this README.md with your package's information
   • Update the LICENSE file if needed

3. Install dependencies:

npm install

4. Start developing:

npm run dev

Example Usage

This is an example of how your package could be used once you publish it. Update this section with your own package's usage:

// This is just a placeholder example - replace with your own package's usage
import { YourFunction } from "your-package-name";

// Use your package
const result = YourFunction();

Development

Setup

1. Clone the repository:

git clone https://github.com/imgarylai/ts-package-starter.git
cd ts-package-starter

2. Install dependencies:

npm install

3. Start developing:

npm run dev

Available Scripts

• npm run build - Build the package with tsup
• npm run dev - Watch mode for development
• npm test - Run tests
• npm run test:coverage - Run tests with coverage
• npm run lint - Lint the code
• npm run type-check - Check types
• npm run docs - Generate documentation
• npm run docs:watch - Generate documentation in watch mode
• npm run clean - Clean build outputs
• npm run prepare - Install git hooks

Project Structure

.
├── src/               # Source code
│   ├── index.ts      # Main entry point
│   └── index.test.ts # Tests
├── .github/          # GitHub configuration
├── .husky/           # Git hooks
├── dist/             # Built files (generated)
├── docs/             # Generated documentation
├── coverage/         # Test coverage reports
└── node_modules/     # Dependencies

Development Workflow

1. Write your code in the src directory
2. Write tests in *.test.ts files
3. Run tests with npm test
4. Build your package with npm run build

Publishing

This package uses semantic-release for automated publishing based on conventional commit messages. The process is fully automated and will:

• Determine the next version number based on commit messages
• Generate release notes
• Update the CHANGELOG.md
• Create a GitHub release
• Publish to npm

How it Works

The release process is triggered by commits to the main branch. The version bump is determined by your commit messages:

• fix: ... - Patch release (1.0.0 → 1.0.1)
• feat: ... - Minor release (1.0.0 → 1.1.0)
• BREAKING CHANGE: ... in commit body - Major release (1.0.0 → 2.0.0)
• feat!: ... - Major release with breaking change (1.0.0 → 2.0.0)

Examples:

# Patch release
git commit -m "fix: correct network timeout issue"

# Minor release
git commit -m "feat: add new API endpoint"

# Major release
git commit -m "feat!: redesign public API
BREAKING CHANGE: The entire public API has been redesigned"

Setup Requirements

To enable automated publishing, you need to:

1. Create an npm account if you don't have one

2. Create an npm access token:

   • Go to npmjs.com and log in
   • Click on your profile picture → "Access Tokens"
   • Click "Generate New Token" (select "Automation" type)
   • Copy the token

3. Add the npm token to your GitHub repository:

   • Go to your GitHub repository settings
   • Click on "Secrets and variables" → "Actions"
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: Your npm access token
   • Click "Add secret"

Development Workflow

1. Write your code and commit using conventional commit messages
2. Push to the main branch
3. semantic-release will automatically:
   • Analyze commit messages
   • Bump version
   • Generate changelog
   • Create GitHub release
   • Publish to npm

Note: Only commits to the main branch trigger releases. When working on features, use feature branches and pull requests.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commits (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

This project uses Conventional Commits. Examples:

• feat: add new feature
• fix: resolve bug issue
• docs: update README
• chore: update dependencies

Building

The project uses tsup for building, which provides:

• Multiple format outputs (ESM, CommonJS)
• TypeScript declaration files
• Source maps
• Tree shaking
• Minification

Dependency Management

This project uses Renovate for automated dependency updates. The configuration includes:

• Automatic merging of minor and patch updates
• Dependencies are updated every weekend
• Updates are automatically rebased
• Non-major dependencies are grouped together
• Node.js version updates are disabled (managed manually)

The Renovate bot will automatically create pull requests for dependency updates according to this schedule and configuration. This helps keep your dependencies up-to-date while minimizing maintenance overhead.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Gary Lai - @imgarylai

Acknowledgments

• tsup for the amazing build tool
• TypeScript for the type system
• Jest for testing
• ESLint for code linting
• Prettier for code formatting
• Husky for git hooks