Maintenance Guide for tRPC Angular Packages

August 4, 2025 · View on GitHub

This guide provides comprehensive instructions for maintaining, testing, and publishing the @heddendorp/trpc-link-angular and @heddendorp/tanstack-angular-query packages.

Repository Structure
Development Setup
Building
Testing
Local Testing
Publishing
Troubleshooting
Package-Specific Notes

Repository Structure

This repository uses Angular workspace with multiple projects:

.
├── projects/
│   ├── trpc-link-angular/          # Angular HttpClient integration
│   │   ├── src/
│   │   ├── package.json
│   │   └── ng-package.json
│   └── tanstack-angular-query/     # TanStack Angular Query integration
│       ├── src/
│       ├── package.json
│       └── ng-package.json
├── examples/                       # Usage examples and guides
├── MAINTENANCE_GUIDE.md           # This file
├── README.md                      # Main project README
├── package.json                   # Root package.json
└── angular.json                   # Angular workspace configuration

Development Setup

Prerequisites

Node.js 24+ (Node 24 is the default version)
Yarn 4.9.2 (managed by Corepack)
Angular CLI 20+

Initial Setup

Clone the repository:

git clone https://github.com/heddendorp/trpc-angular.git
cd trpc-angular

Enable Corepack (for Yarn 4.x):
```
corepack enable
```
Install dependencies:
```
yarn install
```
Verify setup:
```
yarn build
```

Project Commands

Navigate to specific projects:

cd projects/trpc-link-angular
ng build

Or run commands from root:

ng build trpc-link-angular
ng build tanstack-angular-query

Building

Build All Packages

yarn build

Build Individual Packages

# Build trpc-link-angular
ng build trpc-link-angular

# Build tanstack-angular-query
ng build tanstack-angular-query

Development Build

# Watch mode for development
ng build trpc-link-angular --watch
ng build tanstack-angular-query --watch

Output Structure

Built packages are output to:

dist/trpc-link-angular/
dist/tanstack-angular-query/

Each directory contains:

package.json - Package manifest
*.d.ts - TypeScript declarations
esm2022/ - ES2022 modules
fesm2022/ - Flat ES2022 modules
README.md - Package documentation

Testing

Current State

⚠️ Note: Comprehensive test suite is not yet implemented. This is a priority for future development.

Running Tests

# Run all tests
ng test

# Run tests for specific project
ng test trpc-link-angular
ng test tanstack-angular-query

Adding Tests

To add proper tests:

Install testing dependencies:

yarn add -D @angular/testing jasmine karma karma-chrome-headless

Create test files:

# In projects/trpc-link-angular/src/
touch angularHttpLink.spec.ts

# In projects/tanstack-angular-query/src/
touch lib/trpc-query.spec.ts

Configure test environment in karma.conf.js for each project

Local Testing

Link Packages Locally

Build packages:
```
yarn build
```

Link for local testing:

cd dist/trpc-link-angular
yarn link

cd ../tanstack-angular-query
yarn link

Use in test project:

cd /path/to/test-project
yarn link @heddendorp/trpc-link-angular
yarn link @heddendorp/tanstack-angular-query

Test with Example Application

Create test Angular application:
```
ng new test-app
cd test-app
```
Install tRPC dependencies:
```
yarn add @trpc/client @trpc/server
```

Link local packages:

yarn link @heddendorp/trpc-link-angular
yarn link @heddendorp/tanstack-angular-query

Test integration following the examples in the examples/ directory

Publishing

Automated Publishing with Changesets

This project uses Changesets for automated version management and publishing.

How it works:

Changeset files are created to describe changes and their impact
Changesets analyzes these files to determine version bumps
GitHub Actions automatically publishes packages when changesets are merged to main
Changelog and GitHub releases are automatically generated

Creating a changeset:

# Create a changeset describing your changes
yarn changeset

# This will prompt you to:
# 1. Select which packages are affected
# 2. Choose the type of change (major, minor, patch)
# 3. Write a summary of the changes

Changeset Types:

Major: Breaking changes (e.g., API changes, removed features)
Minor: New features, enhancements (backwards compatible)
Patch: Bug fixes, small improvements

Example workflow:

# 1. Make your changes
git checkout -b feature/new-feature
# ... make changes ...

# 2. Create a changeset
yarn changeset
# Select packages: @heddendorp/trpc-link-angular
# Change type: minor
# Summary: "Add new query hook for mutations"

# 3. Commit and push
git add .
git commit -m "feat: add new query hook for mutations"
git push origin feature/new-feature

# 4. Create PR - the changeset file will be included
# 5. Merge PR to main
# 6. Changesets action will create a "Version Packages" PR
# 7. Merge the version PR to trigger release

Manual Publishing

If needed, publish packages individually:

# Build first
yarn build

# Publish individual packages
cd dist/trpc-link-angular
npm publish --access public

cd ../tanstack-angular-query
npm publish --access public

Release Process

Create feature branch and make changes
Create changeset using yarn changeset
Create PR and merge to main (changeset file included)
Changesets action creates a "Version Packages" PR with:

Updated version numbers
Generated changelog entries
Updated package.json files

Merge version PR to trigger automatic publishing to npm

Prerelease Process

For testing changes before official releases, you can create prereleases using the GitHub Actions workflow:

Manual Prerelease (Recommended)

Navigate to GitHub Actions:

Go to the repository on GitHub
Click on "Actions" tab
Select "Prerelease" workflow

Trigger Prerelease:

Click "Run workflow"
Select the branch you want to release from
Choose a prerelease tag (e.g., alpha, beta, rc)
Click "Run workflow"

The workflow will:

Build and test the packages
Create snapshot versions (e.g., 0.1.0-alpha-20240101123456)
Publish to npm with the prerelease tag
Clean up temporary files

Using Prerelease Packages

Install prerelease packages using the tag:

# Install alpha prerelease
npm install @heddendorp/trpc-link-angular@alpha
npm install @heddendorp/tanstack-angular-query@alpha

# Install beta prerelease
npm install @heddendorp/trpc-link-angular@beta
npm install @heddendorp/tanstack-angular-query@beta

Prerelease Notes

Prereleases can be triggered from any branch
No changesets are required - the workflow will create temporary ones
Prerelease versions use timestamp-based naming
Published packages are tagged with the specified prerelease tag
Original package versions and changesets remain unchanged

Pre-publishing Checklist

All packages build successfully
Tests pass (when implemented)
Documentation is updated
Commit messages follow conventional format
Breaking changes are documented

Troubleshooting

Common Issues

Build Failures:

# Clear node_modules and reinstall
rm -rf node_modules
yarn install

# Clear Angular cache
ng cache clean

TypeScript Errors:

Check peer dependency versions
Ensure TypeScript version compatibility
Verify Angular version compatibility

Dependency Conflicts:

# Check for version conflicts
yarn why [package-name]

# Check workspace dependencies
yarn workspaces list

# Check dependency graph
yarn info @heddendorp/trpc-link-angular

# Verbose build for debugging
ng build --verbose

Build Debugging

For detailed build information:

ng build trpc-link-angular --verbose
ng build tanstack-angular-query --verbose

Peer Dependencies

Keep peer dependencies updated:

{
  "peerDependencies": {
    "@angular/common": ">=16.0.0",
    "@angular/core": ">=16.0.0",
    "@trpc/client": "11.4.3",
    "@trpc/server": "11.4.3",
    "rxjs": ">=7.0.0",
    "typescript": ">=5.7.2"
  }
}

Release Process

Version Management

Update version numbers in:

projects/trpc-link-angular/package.json
projects/tanstack-angular-query/package.json

Update CHANGELOG.md with new features and breaking changes
Create release branch:
```
git checkout -b release/v1.0.0
```

Verify publication:

npm info @heddendorp/trpc-link-angular
npm info @heddendorp/tanstack-angular-query

Semantic Versioning

Follow semantic versioning:

Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes (backward compatible)

Breaking Changes

When introducing breaking changes:

Update major version number
Document migration guide
Update examples and documentation
Consider deprecation warnings in previous version

Package-Specific Notes

trpc-link-angular

Purpose: Provides Angular HttpClient integration for tRPC
Key Files: src/lib/angular-http-link.ts
Dependencies: @angular/common, @angular/core, @trpc/client
Build Target: ES2022 with TypeScript declarations

tanstack-angular-query

Purpose: Provides TanStack Angular Query integration for tRPC
Key Files: src/lib/, src/public-api.ts
Dependencies: @tanstack/angular-query-experimental, @trpc/client
Build Target: ES2022 with TypeScript declarations

Contributing

Code Style

Follow Angular coding style guidelines
Use TypeScript strict mode
Follow existing code patterns
Add JSDoc comments for public APIs

Pull Request Process

Fork the repository
Create feature branch
Make changes with tests
Update documentation
Submit pull request

Testing Guidelines

Write unit tests for all new features
Test with different Angular versions
Test peer dependency compatibility
Include integration tests

Future Improvements

Add comprehensive test suite
Implement proper linting configuration
Add more detailed examples
Consider adding subscription support to trpc-link-angular
Optimize bundle size and tree-shaking

Maintenance

Regular dependency updates
Angular version compatibility testing
Performance monitoring
Documentation updates
Community feedback integration

Support

For issues and questions:

Check existing GitHub issues
Create new issue with reproduction steps
Use discussion for general questions
Follow security reporting guidelines for vulnerabilities