Web applications that are still changeable in year three

TypeScript · shared/contracts/invoice.ts

The contract that stops the browser and the server drifting apart. One module defines the shape; the server validates its own response against it before sending, and the browser derives its type from the same definition rather than restating it. Rename a field on the server and the browser fails to compile in the same commit — instead of rendering undefined for a customer and being found weeks later by someone reading a bug report.

// shared/contracts/invoice.ts — imported by both halves. One definition.
import { z } from 'zod';

export const invoice = z.object({
  id: z.string().uuid(),
  reference: z.string(),
  totalMinor: z.number().int(),
  currency: z.enum(['BDT', 'USD', 'EUR']),
  dueOn: z.string().date(),
  settledAt: z.string().datetime().nullable(),
});

export type Invoice = z.infer<typeof invoice>;


// server/routes/invoices.ts
import { invoice, type Invoice } from '../../shared/contracts/invoice';

app.get('/api/invoices/:id', async (req, res) => {
  const row = await db.invoices.findById(req.params.id);
  if (!row) return res.status(404).json({ error: 'NOT_FOUND' });

  // Validated on the way OUT too. A column rename fails here, in our own
  // tests, rather than silently sending a field the browser does not expect.
  res.json(invoice.parse(toApiShape(row)));
});


// src/api/useInvoice.ts
import { invoice, type Invoice } from '../../shared/contracts/invoice';

export function useInvoice(id: string) {
  return useQuery<Invoice>({
    queryKey: ['invoice', id],
    queryFn: async ({ signal }) => {
      const res = await fetch(`/api/invoices/${id}`, { signal });
      if (!res.ok) throw new Error(`Invoice ${id}: ${res.status}`);
      // Not `as Invoice`. A cast trusts the server; this checks it.
      return invoice.parse(await res.json());
    },
  });
}

// Remove `reference` from the schema and every component reading
// invoice.reference stops compiling. That is the whole point of sharing it.

When we would point you elsewhere

If you need a marketing site with a blog and a few landing pages, a well-chosen CMS or a site builder will serve you better and cost a fraction of this. Custom development earns its keep when the rules are yours, the integrations are awkward, or the thing has to scale in a way an off-the-shelf product cannot. If you are unsure which you have, the tell is usually whether you can describe the job in terms of pages or in terms of what the software must not allow to happen.