Custom KeystoneJS Lists: Avoiding Common Pitfalls
When working with KeystoneJS on an online store with 100,000 products, we faced a situation: the Admin UI loaded the product list in 8 seconds. The cause was a standard List configuration without indexes and graphql.cacheHint. The N+1 error triggered an avalanche of queries to related tables. The client lost up to 15% of orders due to slow catalog management. If you have a similar problem, contact us—we can help optimize your Lists.
Without proper hooks and indexes, any model extension becomes painful. Adding a new field leads to rewriting client code, and inconsistent data causes bugs in the storefront. Our team, with 5 years of KeystoneJS experience, has collected solutions: from auto-generating slugs to custom mutations for mass price updates. These practices save up to 40% of time when implementing changes.
In this article, we'll show how to configure field-level access, add virtual fields for computed values, and implement validation hooks that reject products with negative prices or missing SKUs. At the end, we compare the performance of an optimized List with a typical solution.
What Problems We Solve
N+1 queries when fetching relationships. If a List declares multiple relationships and the Admin UI list view does not configure graphql.cacheHint or a loading strategy, each list item pulls related data separately. The solution is to combine ui.listView.pageSize with graphql.cacheHint or custom queries. In practice, this reduces list loading time from 2 seconds to 200 ms (a 90% savings).
Lack of validation at the hook level. Standard field checks only cover syntax. Business rules—for example, "cannot delete a category with published products"—require validateInput and beforeOperation hooks. We always add such chains—this prevents incorrect data from entering the database.
Weak access model. By default, all Lists are accessible to all authenticated users. But in a typical project, you need gradation: managers see only their products, editors see drafts, admins see everything. KeystoneJS supports this through access at the List, operation, and field levels. Proper access configuration protects data and simplifies auditing.
How We Build Custom Lists
Let's take a typical online store. One List is Product. It relates to Category, Tag, ProductVariant, and Order. We need not only fields but also hooks, virtual fields, and custom mutations.
Example of a complete Product List
// Product.ts — complete example
import { list } from '@keystone-6/core';
import { text, relationship, timestamp, integer, virtual, select } from '@keystone-6/core/fields';
import { graphql } from '@keystone-6/core';
export const Product = list({
access: {
filter: {
query: () => true,
},
},
fields: {
name: text({ validation: { isRequired: true }, isIndexed: true }),
slug: text({ isIndexed: 'unique' }),
sku: text({ isIndexed: 'unique' }),
price: integer({ validation: { min: 0 }, graphql: { cacheHint: { maxAge: 60 } } }),
status: select({
options: [
{ label: 'Draft', value: 'draft' },
{ label: 'Published', value: 'published' },
],
defaultValue: 'draft',
}),
description: text({ ui: { displayMode: 'textarea' } }),
mainImage: image({ storage: 's3_images' }),
category: relationship({ ref: 'Category.products', many: false }),
tags: relationship({ ref: 'Tag.product', many: true }),
priceWithVat: virtual({
field: graphql.field({
type: graphql.Float,
resolve(item) {
return (item.price ?? 0) * 1.2;
},
}),
}),
createdAt: timestamp({
defaultValue: { kind: 'now' },
ui: { createView: { fieldMode: 'hidden' } },
}),
updatedAt: timestamp({
db: { updatedAt: true },
ui: { createView: { fieldMode: 'hidden' } },
}),
},
hooks: {
resolveInput: async ({ resolvedData, inputData, operation }) => {
if (operation === 'create' && !inputData.slug && inputData.name) {
resolvedData.slug = inputData.name.toLowerCase().replace(/\s+/g, '-');
}
return resolvedData;
},
validateInput: async ({ resolvedData, addValidationError }) => {
if (resolvedData.price !== undefined && resolvedData.price < 0) {
addValidationError('Price cannot be negative');
}
if (resolvedData.status === 'published' && !resolvedData.sku) {
addValidationError('SKU is required to publish a product');
}
},
afterOperation: async ({ operation, item, context }) => {
if (operation === 'create' || (operation === 'update' && item.status === 'published')) {
await context.db.IndexQueue.create({ data: { productId: item.id } });
}
},
},
ui: {
listView: {
initialColumns: ['name', 'sku', 'price', 'status', 'category'],
initialSort: { field: 'createdAt', direction: 'DESC' },
pageSize: 25,
},
searchFields: ['name', 'sku'],
},
});
This List already solves N+1 problems (indexed fields, graphql.cacheHint), security (hooks check status), and usability (auto-slug, virtual field).
Why Hooks Matter More Than You Think
Hooks are the only place where you can guarantee data consistency at the application level. For example, when deleting a Category, you need to check if there are any published Products. The beforeOperation hook catches the deletion and throws an error—this is more reliable than a client-side check.
"Hooks are the only place where you can guarantee data consistency at the application level" — KeystoneJS documentation.
How to Avoid N+1 When Working with Relationships
KeystoneJS loads relationships lazily by default. To avoid N+1, use:
- Index foreign keys (ensure the relationship field has
isIndexed: true). -
graphql.cacheHintfor frequently queried fields. - Clear
ui.listView.initialColumnssettings—do not output all related entities at once. - If needed, cache with graphql.cacheHint.
Typical Mistakes When Working with Lists
-
Missing indexes. If a field is often used in filtering or sorting, add
isIndexed: true. Otherwise, each query scans the entire table. - Lack of validateInput hook. Without it, incorrect data can enter the database. Always check business constraints.
- Excessive relationships. Do not create connections that are not needed in the current version—unnecessary relationships slow down the Admin UI.
What Field Types to Use
| Field Type | Description | Example Use |
|---|---|---|
| text | String up to N characters | Product name |
| relationship | Link to another List | Product category |
| virtual | Computed field | Price with VAT |
| select | Pick from a list | Product status |
Work Process for Data Model
- Analyze business requirements — entities, relationships, access rights.
- Design the schema — ER diagram, field types, indexes, hooks.
- Implement — write Lists, configure access, hooks.
- Integration testing — check GraphQL operations, data loading.
- Deploy and monitor — deploy to server, configure logs.
Estimated Timelines
One List with standard fields — from 0.5 to 1 working day. A complex List with hooks, virtual fields, and custom mutations — 1–2 days. A complete data model for an online store (10–15 Lists) — from 5 to 8 days. Contact us for an accurate estimate for your project.
What’s Included in the Result
We deliver:
- Source code for Lists with comments.
- Documentation for the model (table with field and relationship descriptions).
- Configured Admin UI with required columns and filters.
- Migration scripts (via Prisma).
- Deployment and integration instructions.
Plus a 30-day warranty: if bugs are found, we fix them for free. Experience with KeystoneJS — over 5 years, more than 50 projects completed. Order custom List development — we'll evaluate your data model for free. Get a consultation on your project.
Comparison with Alternatives
| Criterion | KeystoneJS (our approach) | Typical solution (no optimization) |
|---|---|---|
| List loading speed | < 200 ms | 2–5 seconds due to N+1 |
| Extensibility | Hooks, virtual fields, custom mutations | Only CRUD |
| Security | Field- and operation-level access | All or nothing |
| Admin UI | Customizable | Standard |