keystonejs / keystonejs/keystone

Improve custom field documentation

Open
#7,923 2 comments 6 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
10k
Forks
1.3k
Avg merge
19h 14m
Merged PRs (30d)
19

Description

I've been trying to create my own "Select images from media gallery" custom field which basically just replicates [this document component block extension](https://github.com/beemstream/keystone-document-gallery), but I feel like I'm basically throwing my head against a wall trying to understand what all the different custom field config options actually do. While I do appreciate that everything is typed, reverse engineering from the types alone is very painful.

Here's some things I think would be very helpful if explained in documentation:

1. What is the config object passed into your custom field function? For example:
```ts
export function text({
isIndexed,
...config // <-- this
}
```
2. Explanation of the `graphql` object exported from `@keystone-6/core`
2. Detailed explanation of the `input` and `output` properties required by the `fieldType()` function
2. How does this magical `controller` object work? How does it hook in to everything else? Maybe some simple diagrams?
2. Detailed explanation of all the properties in the following types:
- `FieldControllerConfig`
- `FieldController`

I'm sure there's more that I've missed, but better documentation for custom fields would be a god-send.

Contributor guide

Open the contributing guide

Research direction

No documentation file is named. Start by tracing the custom field function, the graphql export, fieldType() input and output properties, and the FieldControllerConfig and FieldController types. Done means the custom-field configuration and controller behavior are explained with practical examples, including the requested diagrams where useful.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql, typescript
Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.