From Excel Data to End-to-End Type-Safe tRPC Client and Server

Server router type flows to the client

Generate customersRouter; mount it on appRouter; the client infers everything. No duplicated Customer type on the front end.

Input (sheet: Customers): id,name,email,active
Router name: customersRouter

Generated exports:
  export const customersRouter = router({ list, getById, create, update, delete });
  export interface Customer { id?: number; name?: string; email?: string; active?: boolean; }
  export type CustomerRouter = typeof customersRouter;

Client (types inferred, zero manual decls):
  const { data } = api.customers.list.useQuery({ page: 1, pageSize: 20 });
  // data: { data: Customer[]; page: number; pageSize: number }  (inferred)

Type a standalone client from the exported router type

For an external/standalone client you parameterize createTRPCClient with the exported router type.

import { createTRPCClient, httpBatchLink } from "@trpc/client";
import type { CustomerRouter } from "./customersRouter";

const client = createTRPCClient<CustomerRouter>({
  links: [httpBatchLink({ url: "/api/trpc" })],
});

await client.getById.query({ id: "..." }); // fully typed from the export

Read vs write input types differ

Because the base schema is optional but createSchema is required, the inferred create input demands every field while read shapes are loose.

// Inferred from generated schemas:
type CustomerRead   = z.infer<typeof CustomerSchema>;       // all fields optional
type CustomerCreate = z.infer<typeof customerCreateSchema>; // all fields required
type CustomerUpdate = z.infer<typeof customerUpdateSchema>; // partial + id: string(uuid)

api.customers.create.useMutation(); // input requires every field
api.customers.update.useMutation(); // input: partial + required id

Reuse the interface without tRPC

The exported interface is a plain TS type you can import anywhere, including non-tRPC code paths.

import type { Customer } from "./customersRouter";

function CustomerBadge({ customer }: { customer: Customer }) {
  return <span>{customer.name}</span>;
}
// Same shape the server validates -> no drift between prop type and API.

Rename a field and let the compiler find usages

Change a column header, regenerate, and TypeScript flags every stale reference on the client — the payoff of a single source of truth.

Spreadsheet: rename 'email' -> 'emailAddress', regenerate.

Generated interface now: emailAddress?: string  (email removed)

Client code still using customer.email:
  Property 'email' does not exist on type 'Customer'. Did you mean 'emailAddress'?
// One regenerate surfaces every place that must change.

ISO YYYY-MM-DD columns infer to z.string(), so the client type for that field is string, not Date. If your client expects a Date, tighten the field to z.coerce.date() after generating — the inferred client type updates accordingly.

Every field in ${Entity}Schema is .optional(), so the inferred read type marks each field as possibly undefined. That's intentional (partial records are valid on read); create re-requires all fields via .required(). If a field is always present on read, mark it required in the base schema by hand.

The schema/interface types id from your data (often number), but getById/delete/update require z.string().uuid(). The client will need a string id for those calls while the interface says number. Reconcile by editing the id validator to match your real key type so client types are consistent.

On Free / Pro / Pro+Media the tool throws tRPC Router Builder requires Developer tier. and shows an upgrade overlay — no router, no types. Generate on a Developer account.

If a column mixes numbers with any non-numeric value, it can't be z.number() and falls back to z.string(), so the client type becomes string. Clean the source column if you need a numeric client type.

For a multi-tab workbook the exported root type is export type ${PascalCase(routerName)} (e.g. AppRouter for appRouter), and sub-router entity names come from sheet names. Type your client from this root type and name tabs deliberately.

A column with no non-empty samples infers z.string(), giving a string client type even if the field is meant to be numeric or boolean. Include sample data for every column you want strongly typed.

SheetJS reads row 1 as field names, which become your typed fields. A stray preamble row would produce nonsense field names (and types) on the client. Keep only the field names in row 1.

Two columns with the same header are disambiguated by SheetJS (e.g. email, email_1), so the client interface gains a suffixed field. Rename duplicates in the source to keep clean client types.

The on-page preview shows the first 4,000 characters. Copy (full string) or Download to get the complete file, including all exported types, before importing on the client.