In the first post of this series I made the case for agreeing on an OpenAPI contract before anyone writes code. This one is about the tool that makes the contract actually pay off.

Hand-writing the frontend’s API layer is one of those jobs nobody admits to enjoying. You copy types out of the backend docs, write the same request wrapper for the fortieth time, and three weeks later someone renames a field and half your calls quietly break. Orval deletes that job. Point it at your OpenAPI spec and it generates the client code for you: typed functions for every endpoint, models that match the contract exactly, and mocks you can develop against before the backend exists.

Why the frontend team likes it

#

The mock generation is the underrated part. Once the spec is agreed, the frontend can spin up a fake server and build the entire UI against it, instead of waiting for endpoints that are perpetually “almost done”. When the real backend lands, you point the client at it and things mostly just work, because both sides were built from the same document.

The other win is that the boring code is now correct by construction. Nobody fat-fingers a field name in a hand-rolled request body, because nobody writes a hand-rolled request body anymore.

Why the backend team likes it too

#

The spec being the single source of truth changes the day-to-day conversations. Instead of chat threads asking “what does this endpoint return again?”, the frontend just reads the generated types. Backend devs get interrupted less, and they get feedback sooner: if the frontend builds against the mocks and something about the API feels awkward, you find out while it’s still cheap to change, not after it’s in production.

How it fits the workflow

#

Nothing fancy. The backend proposes the spec, both teams review it, the frontend generates the client and mocks with Orval and starts building, and the backend implements the real endpoints to the same contract. When the spec changes, both sides regenerate, and the compiler tells you exactly what broke. That last part is the whole point: drift between frontend and backend becomes a compile error instead of a production bug.

Setting it up

#

Install it as a dev dependency, along with whatever the generated code will import. For React Query hooks and mocks that’s TanStack Query, MSW and Faker:

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

Then add an orval.config.ts at the root of the project. This one is close to the example in Orval’s own docs:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

client decides what you get: plain fetch or axios functions, hooks for React Query, Vue Query, Svelte Query or SWR, Angular services, or Zod schemas. The includeHttpResponseReturnType: false line makes the fetch client return the response body itself rather than { data, status }, which is usually what a component wants.

Add a script so nobody has to remember the command:

{
  "scripts": {
    "api": "orval"
  }
}

npm run api writes the hooks and models. A component then uses them like any other React Query hook, with the types already filled in:

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

Rename a field in the spec, run npm run api again, and pet.name turns red everywhere it’s used. That’s the drift check from above, and it costs nothing to run.

Developing against the mocks

#

With mock: true, Orval also writes an MSW request handler for each endpoint, returning Faker data shaped like the response schema, plus a function that returns all of them. Hand that list to MSW’s setupWorker in the browser or setupServer in tests and the app runs against a fake backend that already matches the contract. Each handler also takes an override, so a test can return a specific payload, an empty list or an error state without anyone writing a fixture by hand.

That’s the part that lets the frontend start on day one. The mocks aren’t a separate artefact someone has to maintain; they’re regenerated from the same spec as the client, so they can’t fall behind it.

Orval vs openapi-generator, openapi-typescript and Hey API

#

They all start from an OpenAPI spec, but they stop at different places.

If you only need types, openapi-typescript is the lightest option and it’s hard to argue with. openapi-generator earns its place when the spec has to feed more than one language; its TypeScript output works, but it reads like it was written for Java first. Between Orval and Hey API it mostly comes down to taste and which one’s output you’d rather read. I keep using Orval because the mocks come out of the same run as the hooks, and that’s the feature that changed how the two teams work together.

It’s not glamorous tooling. It just quietly removes a whole category of arguments between teams, and I’ll take that trade every time.

The waiting game

#

The traditional flow is sequential. Backend designs and builds the API, and only once the endpoints actually work does frontend start integrating. Every backend delay lands directly on the frontend’s calendar, and the frontend’s calendar is usually where the release date lives.

Contract first, code second

#

With a schema-first flow, both sides start almost at the same time. Before any code exists, the API’s structure goes into an OpenAPI schema — every endpoint, request and response model, auth method and error code. That document becomes the contract between frontend and backend.

The payoff is immediate. Everyone understands the feature the same way before it’s built. Frontend can build UI while backend is still implementing. Changes move faster because there’s one agreed source of truth to update. And you can generate a mock server straight from the schema, so frontend testing starts before a single real endpoint exists.

How it runs in practice

#

1. Gather requirements, same as for anything.
2. Design the schema: endpoints, request/response models, authentication, error codes.
3. Have both frontend and backend review it — this is where the contract earns its keep.
4. Generate a mock server (Swagger and Postman both do this) and let frontend integrate against it.
5. Backend implements the real endpoints to the same schema.
6. Swap mocks for real endpoints as they land, testing continuously so the contract holds.
7. Keep talking. The schema is a living document, not a stone tablet.

The catches

#

It isn’t free. Writing a thorough schema upfront takes real time. When requirements change, the schema has to change first, and the ripples hit both teams. And everyone needs at least a working familiarity with OpenAPI and the tooling around it.

Even so, I’ve never seen the upfront cost lose to the integration chaos it prevents. Frontend starts on day one, and the arguments happen over a document instead of over broken builds.

Gwangbokjeol (광복절), on 15 August, is Korea’s National Liberation Day, marking the end of Japanese colonial rule in 1945. Zdog is a small JavaScript library for drawing 3D-ish illustrations on a <canvas> or in SVG. Its shapes have real positions in 3D space and turn like 3D objects, but they’re drawn as flat shapes, so you get something that looks like a flat illustration you can spin rather than a 3D render. That suits something simple like a flag.

A minimal Zdog example

#

Two shapes, drag to rotate, and an animation loop:

<canvas class="zdog-canvas" width="240" height="240"></canvas>
<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
<script>
  const illo = new Zdog.Illustration({
    element: '.zdog-canvas',
    dragRotate: true, // drag to turn the scene
  });

  // a square, pushed back
  new Zdog.Rect({
    addTo: illo,
    width: 80,
    height: 80,
    translate: { z: -30 },
    stroke: 8,
    color: '#0047a0',
  });

  // a filled circle, pulled forward
  new Zdog.Ellipse({
    addTo: illo,
    diameter: 60,
    translate: { z: 30 },
    stroke: 8,
    color: '#cd2e3a',
    fill: true,
  });

  function animate() {
    illo.rotate.y += 0.02;
    illo.updateRenderGraph();
    requestAnimationFrame(animate);
  }
  animate();
</script>

Each shape joins the scene with addTo, and translate.z is what makes it 3D: turn the scene and the circle swings round in front of the square. updateRenderGraph() updates and redraws everything, which is why it sits inside the loop.

Official Docs

#

https://zzz.dog/

The code used is available to view on CodePen.

My Example

#

Here’s how I set it up.

Why SASS at all?

#

Plain CSS gets messy once a site grows past a handful of pages. SASS gives you variables, nested rules, mixins and functions, so things like colours and common layout snippets live in one place instead of being copy-pasted everywhere. The best part for Hugo users is that Hugo Pipes compiles SCSS for you — no separate build tool, no watcher scripts.

Two pages worth keeping open while you work:

• The SASS documentation
• Hugo’s SCSS/SASS support docs

Setting it up

#

1. Sort out the assets directory

#

Hugo looks for an assets folder at the root of your project, so create one (or move yours) there. If you’d rather keep it nested inside resources, point Hugo at it in config.toml:

assetDir = "resources/assets"

2. Make a sass folder

#

Inside assets, create a folder called sass. Your SCSS files live here.

3. Add the entry point

#

Create main.scss inside the sass folder. This is the file Hugo will compile, so drop in a bit of SCSS to prove it works:

// assets/sass/main.scss

// Variables
$primary-color: #3498db;

// Mixin
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// Styles
body {
  font-family: Arial, sans-serif;
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

4. Wire it into your template

#

In your head.html partial, load and minify the compiled stylesheet:

{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

Just make sure the filename here matches your actual entry point (main.scss).

Splitting your styles up

#

Once things grow, split the SCSS into partials and import them from main.scss:

// assets/sass/_variables.scss
$primary-color: #3498db;

// assets/sass/_mixins.scss
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// assets/sass/main.scss
@import "variables";
@import "mixins";

body {
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

That’s honestly all there is to it. Four steps, and Hugo recompiles your styles on every build. I went in expecting a fight with the asset pipeline, and it just worked.