From 0d024c543935321892430ebd4c90da7cea8ab13a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 10:43:08 +0000 Subject: [PATCH 1/3] docs: add oRPC evaluation report for issue #349 Comprehensive evaluation of oRPC as potential replacement for @ts-rest: - Catalog of current @ts-rest usage (shared, backend, frontend packages) - Feature comparison between @ts-rest and oRPC - Proof-of-concept feasibility assessment - Risk evaluation for migration - Strategic recommendation: Stay with @ts-rest Key findings: - @ts-rest is actively maintained (v3.52.1 released March 2025) - oRPC lacks dedicated Fastify adapter (critical blocker) - Migration would require 4-7 weeks for marginal benefit - Current implementation is stable and well-tested Closes #349 https://claude.ai/code/session_01G3hs92h8EGmhEzXBP8kzwn --- docs/evaluations/orpc-evaluation-issue-349.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/evaluations/orpc-evaluation-issue-349.md diff --git a/docs/evaluations/orpc-evaluation-issue-349.md b/docs/evaluations/orpc-evaluation-issue-349.md new file mode 100644 index 0000000..51bcca2 --- /dev/null +++ b/docs/evaluations/orpc-evaluation-issue-349.md @@ -0,0 +1,189 @@ +# oRPC Evaluation Report - Issue #349 + +**Date:** 2026-01-29 +**Status:** Complete +**Recommendation:** Stay with @ts-rest + +## Executive Summary + +After thorough investigation, **I recommend staying with @ts-rest**. The primary concern motivating this evaluation—that @ts-rest has been inactive for 8 months—is **factually incorrect**. The repository shows active maintenance with v3.52.1 released in March 2025, regular commits through January 2025, and 194 total releases. + +--- + +## 1. Current @ts-rest Usage Catalog + +### Dependencies + +| Package | Dependency | Version | +|---------|-----------|---------| +| shared | `@ts-rest/core` | ^3.52.1 | +| backend | `@ts-rest/fastify` | ^3.52.1 | +| frontend | `@ts-rest/core` | ^3.52.1 | + +### Key Integration Points + +**Shared Package (`packages/shared/src/api-contract.ts`)** +- ~700 lines of API contract definition +- 22+ endpoints defined using `initContract()` +- 40+ Zod schemas for validation +- Custom metadata for rate limiting and content types + +**Backend Package (`packages/backend/src/api/routes-ts-rest.ts`)** +- ~1,440 lines of Fastify route handlers using `initServer()` +- Full CRUD operations for: scans, projects, runs, pages, rules, artifacts +- Integration with Swagger via metadata + +**Frontend Package** +- `client.ts` - tsRestClient initialization with custom fetch/retry logic +- `projects.ts`, `runs.ts`, `pages.ts`, `rules.ts` - Type-safe API services +- Direct Pinia store integration + +### Features Currently Used + +1. **Contract-first design** with Zod validation +2. **Path parameters** (`/projects/:projectId`) +3. **Query parameters** with coercion (`z.coerce.number()`) +4. **Multiple response status codes** (200, 202, 400, 404) +5. **Binary responses** (screenshots, diff images) +6. **Custom metadata** (rate limiting, content-type headers) +7. **Swagger/OpenAPI generation** via route metadata + +--- + +## 2. Feature Comparison + +| Feature | @ts-rest | oRPC | +|---------|----------|------| +| **Fastify Adapter** | ✅ Dedicated `@ts-rest/fastify` | ⚠️ Generic Node.js HTTP only | +| **Vue 3 Support** | ✅ Via `@ts-rest/core` | ⚠️ Via Pinia Colada (different pattern) | +| **Zod Integration** | ✅ Native | ✅ Native + Valibot, ArkType | +| **OpenAPI Generation** | ✅ Via metadata + @fastify/swagger | ✅ Built-in automatic | +| **Maturity** | ✅ 194 releases since 2022 | ⚠️ v1.0 released Dec 2025 | +| **Contract-First** | ✅ Excellent | ✅ Excellent | +| **Binary Responses** | ✅ Working | ❓ Unknown | +| **Active Maintenance** | ✅ v3.52.1 (March 2025) | ✅ Active | + +### oRPC Advantages + +- Automatic OpenAPI spec generation (no manual metadata) +- Support for multiple validation libraries +- Dual RPC/REST endpoint serving +- Modern architecture + +### @ts-rest Advantages + +- **Dedicated Fastify adapter** (critical for this project) +- Already fully integrated and tested +- 105 open issues with community support +- More mature ecosystem (3+ years) +- No migration risk + +--- + +## 3. Proof-of-Concept Feasibility Assessment + +### Migration Scope + +| Component | Files Affected | Lines of Code | Effort | +|-----------|---------------|---------------|--------| +| API Contract | 1 | ~700 | HIGH | +| Backend Routes | 1 | ~1,440 | HIGH | +| Frontend Services | 5 | ~400 | MEDIUM | +| Integration Tests | 10+ | ~2,000+ | HIGH | +| Documentation | 5+ | ~500 | LOW | + +### Critical Blockers + +1. **No Fastify adapter**: oRPC doesn't mention Fastify support. Would require: + - Custom adapter implementation, OR + - Migration from Fastify to Express/generic HTTP + +2. **Vue client pattern change**: oRPC uses Pinia Colada, not direct client calls + +3. **Binary response handling**: No documented support for Buffer responses + +### PoC Recommendation + +**Not recommended at this time.** The lack of Fastify adapter is a fundamental blocker. Creating a PoC would require either: +- Writing a custom Fastify adapter for oRPC +- Migrating from Fastify (major breaking change) + +--- + +## 4. Risk Evaluation + +### Migration Risks + +| Risk | Severity | Likelihood | Impact | +|------|----------|------------|--------| +| No Fastify adapter | HIGH | CERTAIN | Would require custom adapter or framework change | +| Breaking test suite | MEDIUM | HIGH | 20+ integration tests need rewrite | +| Binary response handling | MEDIUM | MEDIUM | May require workarounds | +| Learning curve | LOW | CERTAIN | New patterns for team | +| Bug introduction | MEDIUM | MEDIUM | New code = new bugs | + +### Opportunity Cost + +- Estimated migration effort: **2-4 weeks** +- Testing and stabilization: **1-2 weeks** +- Documentation updates: **1 week** +- **Total: 4-7 weeks of development time** + +### Benefit Analysis + +The primary benefits oRPC offers (automatic OpenAPI, multi-validator support) provide marginal improvement over current implementation: +- OpenAPI already works via @fastify/swagger +- Only Zod is needed (no multi-validator requirement) + +--- + +## 5. Strategic Decision + +### Recommendation: **Stay with @ts-rest** + +### Rationale + +1. **False premise**: @ts-rest is actively maintained (v3.52.1 released March 2025) +2. **Fastify blocker**: oRPC lacks dedicated Fastify support +3. **High migration cost**: 4-7 weeks of development for marginal benefit +4. **Working solution**: Current implementation is stable and well-tested +5. **Risk/reward**: High risk, low reward + +### Alternative Actions (Instead of Migration) + +1. **Monitor oRPC**: Revisit when Fastify adapter is available +2. **Contribute to @ts-rest**: If features are missing, consider PRs +3. **Document current patterns**: Improve ts-rest.md guide +4. **Stay updated**: Keep @ts-rest at latest version + +### If Migration Becomes Necessary Later + +Triggers that would justify reconsidering: +- @ts-rest becomes truly unmaintained (no releases for 12+ months) +- oRPC releases official Fastify adapter +- Critical security vulnerability in @ts-rest +- Requirement for multi-validator support + +--- + +## Appendix: Sources + +### @ts-rest Repository Activity + +- Latest release: **v3.52.1** (March 4, 2025) +- Latest commit: January 31, 2025 +- Open issues: 105 +- Total releases: 194 +- Source: [https://github.com/ts-rest/ts-rest](https://github.com/ts-rest/ts-rest) + +### oRPC Documentation + +- Official website: [https://orpc.dev/](https://orpc.dev/) +- GitHub: [https://github.com/unnoq/orpc](https://github.com/unnoq/orpc) +- v1.0 Announcement: [https://orpc.unnoq.com/blog/v1-announcement](https://orpc.unnoq.com/blog/v1-announcement) +- LogRocket comparison: [https://blog.logrocket.com/trpc-vs-orpc-type-safe-rpc/](https://blog.logrocket.com/trpc-vs-orpc-type-safe-rpc/) + +--- + +*Report generated: January 29, 2026* +*Evaluation performed by: Claude Code Agent* From 3cd6e4a46bdd42d7d818b4697554106fe9f30337 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 10:46:26 +0000 Subject: [PATCH 2/3] docs: correct oRPC evaluation - @ts-rest IS inactive Updated evaluation with correct @ts-rest activity data: - Last commit: June 2, 2025 (~8 months ago) - Issue #349 concern is VALID Revised recommendation: - Stay with @ts-rest SHORT-TERM (Fastify adapter blocker) - Prepare for migration (monitor oRPC, consider tRPC backup) - Build PoC when oRPC releases Fastify adapter Key findings unchanged: - oRPC lacks Fastify adapter (critical blocker) - Migration effort: 4-7 weeks - tRPC as backup option (has Fastify adapter) https://claude.ai/code/session_01G3hs92h8EGmhEzXBP8kzwn --- docs/evaluations/orpc-evaluation-issue-349.md | 132 +++++++++++------- 1 file changed, 80 insertions(+), 52 deletions(-) diff --git a/docs/evaluations/orpc-evaluation-issue-349.md b/docs/evaluations/orpc-evaluation-issue-349.md index 51bcca2..81d1649 100644 --- a/docs/evaluations/orpc-evaluation-issue-349.md +++ b/docs/evaluations/orpc-evaluation-issue-349.md @@ -2,11 +2,13 @@ **Date:** 2026-01-29 **Status:** Complete -**Recommendation:** Stay with @ts-rest +**Recommendation:** Monitor both options, prepare for potential migration ## Executive Summary -After thorough investigation, **I recommend staying with @ts-rest**. The primary concern motivating this evaluation—that @ts-rest has been inactive for 8 months—is **factually incorrect**. The repository shows active maintenance with v3.52.1 released in March 2025, regular commits through January 2025, and 194 total releases. +The concern raised in issue #349 is **valid**. @ts-rest has been inactive for approximately **8 months** (last commit: June 2, 2025). However, oRPC currently lacks a dedicated Fastify adapter, which is a critical blocker for immediate migration. + +**Recommendation:** Stay with @ts-rest short-term while actively monitoring oRPC for Fastify support. Begin planning for potential migration if @ts-rest remains unmaintained. --- @@ -54,17 +56,18 @@ After thorough investigation, **I recommend staying with @ts-rest**. The primary | Feature | @ts-rest | oRPC | |---------|----------|------| -| **Fastify Adapter** | ✅ Dedicated `@ts-rest/fastify` | ⚠️ Generic Node.js HTTP only | +| **Fastify Adapter** | ✅ Dedicated `@ts-rest/fastify` | ❌ No adapter (Node.js HTTP only) | | **Vue 3 Support** | ✅ Via `@ts-rest/core` | ⚠️ Via Pinia Colada (different pattern) | | **Zod Integration** | ✅ Native | ✅ Native + Valibot, ArkType | | **OpenAPI Generation** | ✅ Via metadata + @fastify/swagger | ✅ Built-in automatic | -| **Maturity** | ✅ 194 releases since 2022 | ⚠️ v1.0 released Dec 2025 | +| **Maturity** | ⚠️ 194 releases, but inactive 8 months | ✅ v1.0 Dec 2025, active development | | **Contract-First** | ✅ Excellent | ✅ Excellent | -| **Binary Responses** | ✅ Working | ❓ Unknown | -| **Active Maintenance** | ✅ v3.52.1 (March 2025) | ✅ Active | +| **Binary Responses** | ✅ Working | ❓ Unknown/undocumented | +| **Active Maintenance** | ❌ Last commit: June 2, 2025 | ✅ Active | ### oRPC Advantages +- **Active development** (critical differentiator) - Automatic OpenAPI spec generation (no manual metadata) - Support for multiple validation libraries - Dual RPC/REST endpoint serving @@ -74,9 +77,8 @@ After thorough investigation, **I recommend staying with @ts-rest**. The primary - **Dedicated Fastify adapter** (critical for this project) - Already fully integrated and tested -- 105 open issues with community support -- More mature ecosystem (3+ years) -- No migration risk +- No migration risk (short-term) +- Known, working solution --- @@ -92,77 +94,103 @@ After thorough investigation, **I recommend staying with @ts-rest**. The primary | Integration Tests | 10+ | ~2,000+ | HIGH | | Documentation | 5+ | ~500 | LOW | -### Critical Blockers - -1. **No Fastify adapter**: oRPC doesn't mention Fastify support. Would require: - - Custom adapter implementation, OR - - Migration from Fastify to Express/generic HTTP +### Critical Blocker -2. **Vue client pattern change**: oRPC uses Pinia Colada, not direct client calls - -3. **Binary response handling**: No documented support for Buffer responses +**oRPC lacks a Fastify adapter.** Migration options: +1. Write a custom Fastify adapter for oRPC +2. Migrate from Fastify to Express (major breaking change) +3. Use generic Node.js HTTP handler with Fastify (potential compatibility issues) ### PoC Recommendation -**Not recommended at this time.** The lack of Fastify adapter is a fundamental blocker. Creating a PoC would require either: -- Writing a custom Fastify adapter for oRPC -- Migrating from Fastify (major breaking change) +A proof-of-concept **could be valuable** to: +1. Test custom Fastify adapter feasibility +2. Verify binary response handling works +3. Measure actual migration effort + +**Suggested scope:** Migrate 2-3 simple endpoints (e.g., `listProjects`, `getProject`) to oRPC with a custom Fastify wrapper. --- ## 4. Risk Evaluation -### Migration Risks +### Staying with @ts-rest Risks + +| Risk | Severity | Likelihood | Impact | +|------|----------|------------|--------| +| Security vulnerability without fix | HIGH | MEDIUM | No patches available | +| Breaking changes in dependencies | MEDIUM | MEDIUM | Zod/Fastify updates may break | +| Feature stagnation | LOW | HIGH | No new features | +| Community abandonment | MEDIUM | MEDIUM | Less support available | + +### Migration to oRPC Risks | Risk | Severity | Likelihood | Impact | |------|----------|------------|--------| -| No Fastify adapter | HIGH | CERTAIN | Would require custom adapter or framework change | +| No Fastify adapter | HIGH | CERTAIN | Requires custom solution | | Breaking test suite | MEDIUM | HIGH | 20+ integration tests need rewrite | | Binary response handling | MEDIUM | MEDIUM | May require workarounds | | Learning curve | LOW | CERTAIN | New patterns for team | | Bug introduction | MEDIUM | MEDIUM | New code = new bugs | -### Opportunity Cost +### Cost-Benefit Analysis -- Estimated migration effort: **2-4 weeks** -- Testing and stabilization: **1-2 weeks** -- Documentation updates: **1 week** -- **Total: 4-7 weeks of development time** +**Migration Cost:** +- Estimated effort: **4-7 weeks** +- Risk: Medium-High (Fastify adapter uncertainty) -### Benefit Analysis - -The primary benefits oRPC offers (automatic OpenAPI, multi-validator support) provide marginal improvement over current implementation: -- OpenAPI already works via @fastify/swagger -- Only Zod is needed (no multi-validator requirement) +**Staying Cost:** +- Short-term: Low (everything works) +- Long-term: Medium-High (unmaintained dependency risk) --- ## 5. Strategic Decision -### Recommendation: **Stay with @ts-rest** +### Recommendation: **Prepare for Migration** + +Given the 8-month inactivity of @ts-rest, the project should: -### Rationale +### Immediate Actions (Next 2-4 weeks) -1. **False premise**: @ts-rest is actively maintained (v3.52.1 released March 2025) -2. **Fastify blocker**: oRPC lacks dedicated Fastify support -3. **High migration cost**: 4-7 weeks of development for marginal benefit -4. **Working solution**: Current implementation is stable and well-tested -5. **Risk/reward**: High risk, low reward +1. **Create a GitHub issue** to track oRPC Fastify adapter development +2. **Pin @ts-rest version** to prevent unexpected breaking changes +3. **Audit current @ts-rest features** used - document exactly what needs to work -### Alternative Actions (Instead of Migration) +### Short-term (1-3 months) -1. **Monitor oRPC**: Revisit when Fastify adapter is available -2. **Contribute to @ts-rest**: If features are missing, consider PRs -3. **Document current patterns**: Improve ts-rest.md guide -4. **Stay updated**: Keep @ts-rest at latest version +4. **Build a minimal PoC** with oRPC + custom Fastify handler for 2-3 endpoints +5. **Monitor oRPC releases** for official Fastify adapter +6. **Evaluate alternative: tRPC** as backup option (has Fastify adapter) -### If Migration Becomes Necessary Later +### Migration Trigger Conditions -Triggers that would justify reconsidering: -- @ts-rest becomes truly unmaintained (no releases for 12+ months) +Begin full migration when ANY of these occur: - oRPC releases official Fastify adapter -- Critical security vulnerability in @ts-rest -- Requirement for multi-validator support +- Security vulnerability discovered in @ts-rest +- @ts-rest reaches 12+ months of inactivity +- Critical dependency (Zod 4, Fastify 6) requires @ts-rest update that won't come + +### Alternative Consideration: tRPC + +If oRPC Fastify support doesn't materialize, consider **tRPC**: +- Has Fastify adapter (`@trpc/server/adapters/fastify`) +- More mature than oRPC +- Active development +- Similar contract-first approach +- Drawback: Less OpenAPI-focused + +--- + +## 6. Summary + +| Aspect | @ts-rest | oRPC | tRPC (backup) | +|--------|----------|------|---------------| +| Maintenance | ❌ Inactive 8mo | ✅ Active | ✅ Active | +| Fastify Support | ✅ Native | ❌ None | ✅ Native | +| Migration Effort | N/A | HIGH | MEDIUM | +| OpenAPI | ✅ Via metadata | ✅ Built-in | ⚠️ Via plugin | +| Recommendation | Short-term only | Monitor | Backup plan | --- @@ -170,10 +198,9 @@ Triggers that would justify reconsidering: ### @ts-rest Repository Activity -- Latest release: **v3.52.1** (March 4, 2025) -- Latest commit: January 31, 2025 +- **Last commit: June 2, 2025** (~8 months ago) +- Last release: v3.52.1 - Open issues: 105 -- Total releases: 194 - Source: [https://github.com/ts-rest/ts-rest](https://github.com/ts-rest/ts-rest) ### oRPC Documentation @@ -187,3 +214,4 @@ Triggers that would justify reconsidering: *Report generated: January 29, 2026* *Evaluation performed by: Claude Code Agent* +*Corrected: Initial analysis incorrectly stated @ts-rest was active* From d974bf7633023001549f00c60949b1b3525d1204 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 11:35:12 +0000 Subject: [PATCH 3/3] docs: add tRPC evaluation as @ts-rest replacement Comprehensive evaluation of tRPC as migration target for issue #349: Key findings: - tRPC is actively maintained (last commit: today!) - Has official Fastify adapter (critical requirement met) - OpenAPI support via trpc-openapi plugin - Vue 3 integration via community packages - Zod compatibility (same validation library) Recommendation: MIGRATE TO tRPC - Estimated effort: 4-6 weeks - Long-term viability: Excellent - Risk level: Acceptable Comparison: - @ts-rest: Inactive 8 months, abandon - tRPC: Active, recommended migration target - oRPC: No Fastify adapter, blocked https://claude.ai/code/session_01G3hs92h8EGmhEzXBP8kzwn --- docs/evaluations/trpc-evaluation-issue-349.md | 273 ++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/evaluations/trpc-evaluation-issue-349.md diff --git a/docs/evaluations/trpc-evaluation-issue-349.md b/docs/evaluations/trpc-evaluation-issue-349.md new file mode 100644 index 0000000..ca047b2 --- /dev/null +++ b/docs/evaluations/trpc-evaluation-issue-349.md @@ -0,0 +1,273 @@ +# tRPC Evaluation Report - Issue #349 + +**Date:** 2026-01-29 +**Status:** Complete +**Recommendation:** **Migrate to tRPC** - viable alternative with Fastify support + +## Executive Summary + +tRPC is a **strong candidate** for replacing @ts-rest. Unlike oRPC, tRPC has: +- ✅ Official Fastify adapter +- ✅ Active development (last commit: **today, January 29, 2026**) +- ✅ OpenAPI support via `trpc-openapi` plugin +- ✅ Vue 3 integration via community packages + +**Recommendation:** Plan migration to tRPC within the next 3-6 months. + +--- + +## 1. tRPC Activity Status + +| Metric | Value | +|--------|-------| +| **Last commit** | January 29, 2026 (today!) | +| **Open issues** | 154 | +| **Maintenance** | ✅ Very active | +| **Maturity** | ✅ Established (since 2020) | + +Recent commits (last 5 days): +- Jan 29: dependency updates (@actions/core v3) +- Jan 28: @clack/prompts update, react-dom optional peer dep +- Jan 27: @actions/github v9, @oxc-project/runtime update + +--- + +## 2. Feature Comparison + +| Feature | @ts-rest (current) | tRPC | oRPC | +|---------|-------------------|------|------| +| **Maintenance** | ❌ Inactive 8 months | ✅ Active (today!) | ✅ Active | +| **Fastify Adapter** | ✅ Native | ✅ Official | ❌ None | +| **Vue 3 Support** | ✅ Direct | ⚠️ Community packages | ⚠️ Pinia Colada | +| **Zod Integration** | ✅ Native | ✅ Native | ✅ Native | +| **OpenAPI** | ✅ Via metadata | ✅ Via trpc-openapi | ✅ Built-in | +| **Contract-First** | ✅ Excellent | ⚠️ Code-first | ✅ Excellent | +| **Binary Responses** | ✅ Working | ✅ Supported | ❓ Unknown | + +--- + +## 3. tRPC Technical Details + +### 3.1 Fastify Adapter + +Official adapter: `@trpc/server/adapters/fastify` + +```typescript +import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify'; +import fastify from 'fastify'; + +const server = fastify({ maxParamLength: 5000 }); + +server.register(fastifyTRPCPlugin, { + prefix: '/trpc', + trpcOptions: { router: appRouter, createContext }, +}); +``` + +**Requirements:** +- Fastify ≥ 3.11.0 +- WebSocket support via `@fastify/websocket` + +### 3.2 Vue 3 Integration + +Community packages available: +- [`@colonel-sandvich/trpc-vue-query`](https://www.npmjs.com/package/@colonel-sandvich/trpc-vue-query) - TanStack Query bridge +- [`trpc-vue-query`](https://github.com/falcondev-oss/trpc-vue-query) - Type-safe composables +- [`usetrpc`](https://github.com/michealroberts/usetrpc) - Vue 3 composables (WIP) + +**Note:** Vue ecosystem is less mature than React, but functional packages exist. + +### 3.3 OpenAPI Generation + +Via [`trpc-openapi`](https://github.com/trpc/trpc-openapi): + +```typescript +import { createOpenApiHttpHandler } from 'trpc-openapi'; +import { generateOpenApiDocument } from 'trpc-openapi'; + +// Generate OpenAPI spec +const openApiDocument = generateOpenApiDocument(appRouter, { + title: 'Diff Voyager API', + version: '1.0.0', + baseUrl: 'http://localhost:3000', +}); + +// Expose REST endpoints +app.use('/api', createOpenApiHttpHandler({ router: appRouter })); +``` + +**Supports:** Express, Next.js, Fastify, Serverless, Node:HTTP + +--- + +## 4. Migration Scope Assessment + +### 4.1 Code Changes Required + +| Component | Current (@ts-rest) | Target (tRPC) | Effort | +|-----------|-------------------|---------------|--------| +| **API Contract** | `initContract()` | `initTRPC.create()` | HIGH | +| **Backend Routes** | `s.router(contract, {...})` | `t.router({...})` | HIGH | +| **Frontend Client** | `initClient(contract)` | `trpc.useQuery()` / `client.query()` | MEDIUM | +| **Validation** | Zod schemas | Zod schemas (same!) | LOW | +| **OpenAPI** | Metadata + Swagger | trpc-openapi plugin | MEDIUM | + +### 4.2 Key Differences + +**Contract Definition:** +```typescript +// @ts-rest (current) +const contract = c.router({ + getProject: { + method: 'GET', + path: '/projects/:id', + responses: { 200: projectSchema }, + } +}); + +// tRPC (target) +const appRouter = t.router({ + getProject: t.procedure + .input(z.object({ id: z.string() })) + .output(projectSchema) + .query(({ input }) => { /* handler */ }), +}); +``` + +**Client Usage:** +```typescript +// @ts-rest (current) +const result = await client.getProject({ params: { id } }); + +// tRPC (target) +const result = await trpc.getProject.query({ id }); +// or with Vue Query: +const { data } = useQuery(['project', id], () => trpc.getProject.query({ id })); +``` + +### 4.3 Migration Effort Estimate + +| Phase | Tasks | Duration | +|-------|-------|----------| +| **Phase 1: Setup** | Install deps, configure tRPC + Fastify | 2-3 days | +| **Phase 2: Backend** | Migrate 22+ endpoints | 1-2 weeks | +| **Phase 3: Frontend** | Migrate 5 services + stores | 1 week | +| **Phase 4: OpenAPI** | Configure trpc-openapi + Swagger | 2-3 days | +| **Phase 5: Tests** | Update 20+ integration tests | 1 week | +| **Phase 6: Polish** | Bug fixes, documentation | 3-5 days | +| **Total** | | **4-6 weeks** | + +--- + +## 5. Risk Evaluation + +### 5.1 Migration Risks + +| Risk | Severity | Likelihood | Mitigation | +|------|----------|------------|------------| +| Vue integration maturity | MEDIUM | MEDIUM | Use proven `trpc-vue-query` package | +| Code-first vs contract-first | LOW | CERTAIN | Acceptable trade-off | +| Binary response handling | LOW | LOW | tRPC supports Buffers | +| Test suite breakage | MEDIUM | HIGH | Incremental migration | +| Learning curve | LOW | CERTAIN | Good documentation | + +### 5.2 Staying with @ts-rest Risks + +| Risk | Severity | Likelihood | Impact | +|------|----------|------------|--------| +| Security vulnerability | HIGH | MEDIUM | No patches for 8+ months | +| Dependency conflicts | MEDIUM | MEDIUM | Zod 4, Fastify updates | +| Community abandonment | MEDIUM | HIGH | Less help available | +| Feature stagnation | LOW | CERTAIN | No improvements | + +### 5.3 Risk Comparison + +| Aspect | Stay with @ts-rest | Migrate to tRPC | +|--------|-------------------|-----------------| +| Short-term risk | LOW | MEDIUM | +| Long-term risk | HIGH | LOW | +| Effort | None | 4-6 weeks | +| Future-proofing | ❌ Poor | ✅ Good | + +--- + +## 6. Strategic Recommendation + +### Decision: **Migrate to tRPC** + +### Rationale + +1. **Active maintenance** - tRPC commits daily vs @ts-rest inactive 8 months +2. **Official Fastify adapter** - No custom adapter needed (unlike oRPC) +3. **OpenAPI support** - Via mature `trpc-openapi` plugin +4. **Zod compatibility** - Same validation library, minimal schema changes +5. **Acceptable effort** - 4-6 weeks is reasonable for long-term stability + +### Migration Plan + +#### Phase 1: Preparation (Week 1) +- [ ] Install tRPC packages +- [ ] Set up parallel tRPC router alongside @ts-rest +- [ ] Migrate 2-3 simple endpoints as PoC +- [ ] Verify Fastify integration works + +#### Phase 2: Backend Migration (Weeks 2-3) +- [ ] Migrate all 22+ endpoints incrementally +- [ ] Keep @ts-rest routes active during transition +- [ ] Update tests as endpoints migrate + +#### Phase 3: Frontend Migration (Week 4) +- [ ] Install `@colonel-sandvich/trpc-vue-query` +- [ ] Migrate API services one by one +- [ ] Update Pinia stores + +#### Phase 4: OpenAPI & Cleanup (Weeks 5-6) +- [ ] Configure `trpc-openapi` for REST endpoints +- [ ] Update Swagger documentation +- [ ] Remove @ts-rest dependencies +- [ ] Final testing and documentation + +### Success Criteria + +- [ ] All 22+ endpoints functional on tRPC +- [ ] All integration tests passing +- [ ] OpenAPI/Swagger documentation working +- [ ] Frontend type-safety maintained +- [ ] No regression in functionality + +--- + +## 7. Comparison Summary + +| Aspect | @ts-rest | tRPC | oRPC | +|--------|----------|------|------| +| **Recommendation** | ❌ Abandon | ✅ **Migrate** | ❌ Not ready | +| **Maintenance** | ❌ 8mo inactive | ✅ Daily commits | ✅ Active | +| **Fastify** | ✅ Yes | ✅ Yes | ❌ No | +| **Vue 3** | ✅ Direct | ⚠️ Community | ⚠️ Different | +| **OpenAPI** | ✅ Metadata | ✅ Plugin | ✅ Built-in | +| **Migration effort** | N/A | 4-6 weeks | Blocked | +| **Long-term viability** | ❌ Poor | ✅ Excellent | ✅ Good | + +--- + +## Appendix: Sources + +### tRPC +- GitHub: [https://github.com/trpc/trpc](https://github.com/trpc/trpc) +- Documentation: [https://trpc.io/docs](https://trpc.io/docs) +- Fastify adapter: [https://trpc.io/docs/server/adapters/fastify](https://trpc.io/docs/server/adapters/fastify) +- OpenAPI plugin: [https://github.com/trpc/trpc-openapi](https://github.com/trpc/trpc-openapi) + +### Vue 3 Integration +- trpc-vue-query: [https://github.com/falcondev-oss/trpc-vue-query](https://github.com/falcondev-oss/trpc-vue-query) +- @colonel-sandvich/trpc-vue-query: [https://www.npmjs.com/package/@colonel-sandvich/trpc-vue-query](https://www.npmjs.com/package/@colonel-sandvich/trpc-vue-query) + +### Comparisons +- tRPC vs OpenAPI: [https://medium.com/@Modexa/ship-faster-with-type-safe-apis-trpc-vs-openapi-9aa977b4331b](https://medium.com/@Modexa/ship-faster-with-type-safe-apis-trpc-vs-openapi-9aa977b4331b) +- trpc-openapi vs ts-rest: [https://catalins.tech/public-api-trpc/](https://catalins.tech/public-api-trpc/) + +--- + +*Report generated: January 29, 2026* +*Evaluation performed by: Claude Code Agent*