Frontend Interfaces Are APIs
Why props, URLs, events, CSS classes and localStorage deserve the same versioning discipline as a REST endpoint – at the latest when several teams work in the same browser.
Frontend Interfaces Are APIs
UserCard.propTypes = {
- name: PropTypes.string.isRequired,
+ fullName: PropTypes.string.isRequired,
avatarUrl: PropTypes.string,
onSelect: PropTypes.func
};
A diff like this sails through review. A rename, the new name is more descriptive, your own application runs, the tests are green, merged. Three weeks later, another team pulls the new version of the shared component library, and their browser console says:
Warning: Failed prop type: The prop `fullName` is marked as required
in `UserCard`, but its value is `undefined`.
That is still the good case, because propTypes at least makes noise. The worse case: the card simply renders without a name, nobody looks at the console, and the bug only gets noticed when a user reports it – two releases later, with a diff in which nothing suspicious remains.
If someone had done the same with a field in a REST response – renamed name to fullName without comment, without announcement and without a version bump – there would be plenty of trouble, and rightly so. With a component prop, exactly this happens all the time, and hardly anyone calls it what it is. Yet the situation is identical: there is a contract between two codebases that are changed and shipped by different teams at different times. That is the definition of an API. The fact that the contract consists of JSX instead of HTTP doesn’t change that.
More surfaces than the architecture diagram shows#
In a portal project I worked on for quite a while, application parts from four teams ran in the same browser tab: a shell, two business applications, an embedded widget. When, after a particularly stubborn integration bug, we once wrote down what these parts actually talk to each other about, we ended up with a list that was considerably longer than anything that had ever appeared in an architecture diagram:
- props and callbacks of the shared component library
- URLs with paths and query parameters that are linked to
- CustomEvents and
postMessagemessages between parts of the page - CSS classes and CSS custom properties that other parts use deliberately
- localStorage keys that more than one module reads
Each of these surfaces had consumers outside the team that maintained it. None of them was versioned. Only the first was documented at all. The REST APIs of the same project, by contrast, had version prefixes, changelogs and a deprecation policy – because everyone understood there that other people’s code depended on them. In the frontend, the same dependency existed, just invisibly.
flowchart LR
subgraph FE[One team’s frontend]
P[Props & callbacks]
U[URLs & parameters]
E[CustomEvents /<br/>postMessage]
C[CSS classes &<br/>custom properties]
S[localStorage<br/>keys]
end
A[Team B:<br/>business application] --> P
B[Users: bookmarks,<br/>shared links] --> U
M[Emails, campaigns,<br/>monitoring checks] --> U
W[Widget in an iframe] --> E
T[Team C:<br/>theming] --> C
X[Old portal script] --> SThe diagram is no exaggeration but the tidied-up version of our list back then. And it explains why “we’re only refactoring internally” goes wrong so often in the frontend: what looks internal has long had consumers.
Props: the contract between teams#
For the component library, we drew the obvious conclusion: it is treated like an API. In concrete terms, that means three things. First, the prop signature is the contract, and propTypes make it machine-readable. Second, Semantic Versioning applies for real – a removed or renamed prop is a breaking change and therefore a major version, no matter how small the diff looks. Third, every change gets a deprecation window: the old form keeps working but warns in development mode.
For the UserCard example above, it looks like this:
import React from 'react';
import PropTypes from 'prop-types';
// v2.3.0: `name` is deprecated in favor of `fullName`.
// Both work until v3.0.0, where `name` will be removed.
export function UserCard({ fullName, name, avatarUrl, onSelect }) {
const displayName = fullName || name;
if (name && process.env.NODE_ENV !== 'production') {
console.warn(
'UserCard: prop `name` is deprecated, use `fullName` instead. ' +
'Support for `name` will be removed in v3.0.0.'
);
}
return (
<div className="user-card" onClick={onSelect}>
{avatarUrl && <img className="user-card__avatar" src={avatarUrl} alt="" />}
<span className="user-card__name">{displayName}</span>
</div>
);
}
UserCard.propTypes = {
fullName: PropTypes.string,
name: PropTypes.string, // deprecated, see above
avatarUrl: PropTypes.string,
onSelect: PropTypes.func
};
That is more code than the pure rename, and exactly this extra effort is the point. It forces the question of whether the rename is worth the price. For an internal helper function, the answer is almost always yes, because the compiler or a search finds all callers. For a published prop, you can’t find the callers – they sit in repositories you have no access to.
For documentation, Storybook has proven itself for us – as a living contract description, not just as a pretty component catalog: for each component there are stories that show the supported prop combinations, including a story for the deprecated form as long as it exists. If you want to know what UserCard can do, you don’t look at the component team’s source code but at the built Storybook instance of the version you use. The team that maintains the library also notices earlier itself when a change touches the contract – a broken story is a clear signal.
URLs: the contract with everyone else#
The second surface is underestimated even more often: the URL. Routes feel like an internal implementation detail of the router, but they are the exact opposite – the most public interface a frontend has. Bookmarks point to a route, as do links shared by email, campaigns, monitoring checks, the neighboring team’s documentation and occasionally a PDF that was printed two years ago. None of these consumers gets an update when someone renames /clients to /customers in the code.
Renaming a route is therefore a breaking change with especially long-lived consumers, and here the deprecation phase is called a redirect. With React Router v4, it’s one line plus discipline:
import { Switch, Route, Redirect } from 'react-router-dom';
<Switch>
<Route path="/customers/:customerId" component={CustomerPage} />
{/* Deprecated 2018-08: keep this redirect for at least 12 months. */}
<Redirect from="/clients/:customerId" to="/customers/:customerId" />
</Switch>
The discipline lies in the comment: the redirect stays until the old links are realistically gone from the world, not until the next cleanup commit. In the portal project, at some point we counted hits on old routes before a redirect was removed – the same practice you use to switch off an old REST endpoint. The numbers were regularly sobering: links we thought were dead were still being called months later.
The same goes for query parameters. If you support ?tab=invoices, you have entered into a contract as soon as the first user shares the link. And the URL is also persisted state: what’s in it survives reloads and travels between browsers – one more reason to design it deliberately instead of leaving it to router chance. Designing deliberately mainly means: domain identifiers instead of internal IDs, no implementation details in the path, and a scheme that a colleague can guess without looking at the code. In my experience, a URL you can read out over the phone also survives the next redesign.
Events and messages: contracts at runtime#
As soon as several application parts run in the same browser, at some point they talk to each other directly – for us via CustomEvents on window and via postMessage to the embedded widget. These messages are the most fleeting form of interface: no type check, no shared repository, often not even a shared deployment. That is exactly why they need the most explicit contract.
We treated every message like a small wire format – a named type, a documented payload schema, a version field:
// Contract: 'cart:item-added' (version 1)
// detail: { version: number, sku: string, quantity: number, source: string }
window.dispatchEvent(new CustomEvent('cart:item-added', {
detail: { version: 1, sku: 'A-4711', quantity: 1, source: 'product-page' }
}));
// Consumer side: tolerate unknown versions instead of guessing.
window.addEventListener('cart:item-added', (event) => {
if (event.detail.version !== 1) return;
updateCartBadge(event.detail.quantity);
});
The version field seems overly cautious until the first time two parts of the page with different release levels run in the same tab. Then it is the difference between an ignored event and an undefined that explodes three functions further on. With postMessage, the origin check comes on top, but the principle stays the same: the receiver validates, the sender promises backward compatibility within a version. Custom Elements v1, by the way, makes this way of thinking official – an element with attributes and events is nothing but an API registered in the browser.
CSS and localStorage: the contracts nobody wanted to make#
The last two surfaces are the most unpleasant, because they are contracts nobody ever entered into deliberately. If you write BEM classes like user-card__avatar into the DOM, you publish them. Somewhere, another team styles against this class, a test selects it, an analytics snippet hooks into it. By the same logic, CSS custom properties that a theme offers to the outside – --brand-primary, --spacing-unit – are a real, intended API and should be maintained as such: named, documented, stable. The unintended variant can be contained by clearly separating which classes are part of the contract and which are generated or marked as private. But the basic rule remains: whatever is observable and stays stable long enough will be used – regardless of what the documentation says about it.
localStorage is the same case, only worse: global per origin, without namespaces, without a schema. A key like user-settings that two modules read is an unintended database API including a migration problem – if one module changes the format, the other parses garbage. On top of that comes a property that sets storage apart from all other surfaces: the old values are already out there. A deployment swaps the code but not the data in thousands of browsers – every format change hits values there that an older version wrote. Since the portal project, I therefore give such keys a prefix with the module name and a version number in the value, and the reading code treats an unknown format like a missing value. Not because that’s elegant, but because the alternative is a production bug you can only diagnose with “clear storage in the DevTools panel”.
Versioning is communication, not bureaucracy#
The objection is obvious: that’s a lot of process for a frontend. But the effort is tiered, and most of it is simply communication. For the component library in our Lerna monorepo, the window for a breaking change looked like this:
- announce the change in the changelog, with the old and the new contract
- a minor version in which both work and the old form warns in development mode
- mark the Storybook story for the old form as deprecated
- removal only in the next major version, with a migration note
That costs maybe an hour per change. The prop rename without this window cost us several days back then, counting everyone involved – debugging in someone else’s codebase, a hotfix, a special release, and the trust between two teams along with it. I have written about the sloppy treatment of code that sits between areas of responsibility before, among other places in Build Scripts as Product Code; frontend interfaces get overlooked in the same way, only more teams depend on them here.
What struck me is that teams don’t fail at the discipline but at the perception. Nobody refuses to version an API cleanly – you just don’t see that you have one. The most effective step was therefore not the tooling but the list from the beginning: write down once which surfaces your own frontend actually offers and who depends on them. Everything on this list that has a consumer outside your own team deserves the three familiar ingredients – an explicit contract, a semantic version, a deprecation window.
Bottom line#
A frontend is not a leaf at the end of the dependency tree but itself a provider of interfaces: props, URLs, events, CSS surfaces, stored keys. As long as a single team owns all of it and ships it in one step, you can ignore that. At the latest when several teams work in the same browser – and the design system and micro-frontend movement is currently making sure that this becomes the norm – the rules apply that have been taken for granted in the backend for years. A breaking change means a major version. Renaming means deprecating. And a harmless-looking diff is exactly as harmless as the number of consumers nobody asked.
Further reading#
- Semantic Versioning 2.0.0 (German version): https://semver.org/lang/de/
- React documentation: typechecking with PropTypes: https://legacy.reactjs.org/docs/typechecking-with-proptypes.html
- MDN: CustomEvent: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
- MDN: Window.postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
- Storybook: https://storybook.js.org/
Revised and translated from German with the help of AI.