All posts
Architecture · 11 min read · Aug 4, 2026

A Data-Driven Registry and One Dynamic Route

A single registry generating many similar pages

Plenty of sites contain a set of pages that are the same page: a catalogue of tools, a directory of services, product pages, locations, documentation entries. Each needs a heading, a description, examples, some metadata, links to siblings. They differ in content and not in structure.

The default approach is a file per page. It works, it is easy to start, and the cost profile is bad in a specific way: adding the fortieth page costs the same as the first, and improving all forty means editing forty files, so in practice nobody improves them.

The pattern

Describe every item as data in one registry. Render every item through one dynamic route. Where an item needs genuinely unique behaviour, lazy-load a component that belongs to it. Three parts, and the separation between them is what does the work.

javascript
// registry.js - one entry per page, purely declarative
export const items = [
  {
    slug: "json-formatter",
    name: "JSON Formatter",
    category: "data",
    tagline: "Format, validate and minify JSON.",
    description: "...",
    keywords: ["json", "pretty print", "validate"],
    examples: [{ label: "Minified input", value: "..." }],
    faqs: [{ q: "Is my data uploaded?", a: "No - it runs in your browser." }],
    related: ["json-compare", "yaml-converter"],
  },
  // ... thirty-nine more
];
Entries carry content and relationships, never markup and never logic.

The route then does what every one of those pages needs, once: resolve the entry, build the metadata, render the shared scaffolding, and mount whatever interactive piece the item declares.

The payoff is improvement, not addition

Adding a page becomes adding an object, which is the benefit people notice first and the smaller one. The larger benefit arrives the first time you want to improve the template.

Adding breadcrumbs, a related-items section, structured data, a feedback control or a better heading hierarchy is one edit that lands on every page at once. In the file-per-page version, each of those is a mechanical change repeated dozens of times, which means it gets done inconsistently or not at all. Over a year, this is the difference between a set of pages that improves and one that ossifies.

Everything else derives from the registry

Once the registry exists, it becomes the single source for far more than the detail pages. Each of these would otherwise be a separate list that drifts out of sync.

Derived from the registryOtherwise maintained as
The index page and its groupingA hand-written listing
Navigation menus and category filtersA separate menu definition
The set of pages to pre-renderAn explicit route list
The sitemapA separate file, usually stale
Related-item linksHand-curated cross-links
Search and filtering dataA duplicated index
Six things that cannot disagree with each other when they share one source.

The sitemap case is the clearest illustration. A hand-maintained sitemap is wrong within weeks of the first addition; a derived one cannot be, because omitting a page from it would require omitting the page itself.

Keep entries declarative

The pattern degrades in one predictable way: entries start carrying markup, then conditional logic, then functions. At that point the registry is code with none of code's affordances, and reading a single page's behaviour requires reading both the entry and the template with all its branches.

  • Entries hold values, not markup - a description is a string, not a block of HTML.
  • Variation is expressed as data the template interprets, not as instructions.
  • Genuine per-item behaviour lives in a component the entry names, not inside the entry.
  • Optional fields are the escape hatch; one item needing something new adds a field, not a branch.

That last point is the discipline that keeps the pattern alive. When one item needs a warning banner, the cheap fix is a conditional in the template for that slug. The right fix is an optional field that any item may set, which costs the same to write and does not accumulate.

Data can be validated, which code cannot be

Because entries are plain data, a short script can assert things a type system would not catch, and run in the build before anything ships.

javascript
// Cheap checks that prevent the whole class of broken pages
assertUnique(items.map((i) => i.slug));
assertEvery(items, (i) => i.name && i.description && i.category);
assertEvery(items, (i) =>
  i.related.every((slug) => bySlug.has(slug))   // no dead cross-links
);
assertEvery(items, (i) => i.description.length <= 160);  // metadata limits
A few assertions replace the review step everyone forgets.

This is the same instinct as asserting that something actually matched rather than silently defaulting: the failure you want is a loud one at build time, not a page that renders with an empty section.

When not to use it

The pattern earns its keep at scale and gets in the way below it. With three or four pages, the indirection costs more than it saves and a file each is genuinely clearer.

It is also wrong when the items are not actually the same page. If half the entries need a fundamentally different information architecture, forcing them through one template produces a design that serves neither group, and the honest answer is two templates - or two registries - rather than one template with a growing set of conditionals.

Conclusion

One registry and one route is a small structural decision with compounding returns. It makes adding an item trivial, makes improving every item at once possible, and lets navigation, pre-rendering, sitemaps and cross-links derive from a single source that cannot contradict itself. Keep the entries declarative, let optional fields absorb variation rather than template branches, validate the data at build time, and recognise the point at which the items stop being the same page.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar