@tecmie/techleadrpc

Contract-first TypeScript RPC package for Techlead.so. This package exports type-safe contract definitions that both server and client can use to ensure end-to-end type safety.

Installation

npm install @tecmie/techleadrpc
# or
yarn add @tecmie/techleadrpc
# or
pnpm add @tecmie/techleadrpc

Philosophy

This package follows a contract-first approach where:

1. Contracts are defined using oRPC and Zod schemas
2. Server implements the contracts
3. Clients consume the contracts with full type safety

We intentionally keep this package minimal and don't prescribe how you should set up your RPC connection. This gives you full control over authentication, headers, fetch configuration, and more.

Usage

Basic Setup

import { createORPCClient, RPCLink, type AppRouterClient } from '@tecmie/techleadrpc'

// Set up your RPC link with your own configuration
const link = new RPCLink({
  url: 'https://api.techlead.so/rpc',
  fetch(url, options) {
    return fetch(url, {
      ...options,
      credentials: 'include', // Your auth strategy
    })
  },
  headers: async () => {
    // Your custom headers
    return {
      'X-Custom-Header': 'value'
    }
  },
})

// Create a fully-typed client
const client: AppRouterClient = createORPCClient(link)

// Make RPC calls with full type safety
const health = await client.healthCheck()
const privateData = await client.privateData()

Next.js Integration

// app/utils/orpc.ts
import { createORPCClient, RPCLink, type AppRouterClient } from '@tecmie/techleadrpc'

export const link = new RPCLink({
  url: `${process.env.NEXT_PUBLIC_SERVER_URL}/rpc`,
  fetch(url, options) {
    return fetch(url, {
      ...options,
      credentials: 'include',
    })
  },
  headers: async () => {
    // Server-side: forward headers from incoming request
    if (typeof window === 'undefined') {
      const { headers } = await import('next/headers')
      return Object.fromEntries(await headers())
    }
    return {}
  },
})

export const client: AppRouterClient = createORPCClient(link)

// app/page.tsx
import { client } from '@/utils/orpc'

export default async function Page() {
  const data = await client.healthCheck()
  return <div>{data}</div>
}

TanStack Query Integration

import { createTanstackQueryUtils } from '@orpc/tanstack-query'
import { createORPCClient, RPCLink, type AppRouterClient } from '@tecmie/techleadrpc'

const link = new RPCLink({
  url: `${process.env.NEXT_PUBLIC_SERVER_URL}/rpc`,
  fetch(url, options) {
    return fetch(url, {
      ...options,
      credentials: 'include',
    })
  },
})

const client: AppRouterClient = createORPCClient(link)

// Create query utilities
export const orpc = createTanstackQueryUtils(client)

// Use in components
function Component() {
  const { data } = orpc.privateData.useQuery()
  return <div>{data?.message}</div>
}

Server Implementation

// server/src/lib/orpc.ts
import { implement } from '@orpc/server'
import { appContract } from '@tecmie/techleadrpc'

const os = implement(appContract)

export const publicProcedure = os.$context<Context>()

// server/src/routers/index.ts
export const appRouter = {
  healthCheck: publicProcedure.healthCheck.handler(() => {
    return 'OK' as const
  }),
  privateData: protectedProcedure.privateData.handler(({ context }) => {
    return {
      message: 'This is private',
      user: context.session?.user,
    }
  }),
}

Exports

Contracts

• appContract - The root contract object
• healthCheckContract - Health check procedure contract
• privateDataContract - Private data procedure contract

Types

• AppContract - Type of the contract object
• AppRouterClient - Type-safe client interface
• ContractRouterClient - Generic contract router client type
• RouterClient - oRPC router client type

Client Utilities (Re-exported for version locking)

• createORPCClient - Create an oRPC client from @orpc/client
• RPCLink - RPC link for fetch-based connections from @orpc/client/fetch
• onError - Error interceptor utility from @orpc/client
• ClientLink - Client link type from @orpc/client

Why This Approach?

We believe in giving developers full control over their RPC setup. Instead of prescribing authentication strategies, header management, or fetch configuration, we:

1. Export clean contracts - Just the type definitions and schemas
2. Re-export oRPC utilities - Locked to compatible versions
3. Let you configure everything - Full control over your RPC link setup

This makes the package:

• ✅ Flexible - Use any auth strategy, any headers, any fetch config
• ✅ Transparent - You see exactly how the connection is set up
• ✅ Maintainable - No magic configuration or hidden defaults
• ✅ Testable - Easy to mock and test your own setup

License

MIT