Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide feedback when a <PrismicLink> component receives an invalid value #167

Open
angeloashmore opened this issue Nov 10, 2022 · 1 comment
Labels
enhancement New feature or request

Comments

@angeloashmore
Copy link
Member

angeloashmore commented Nov 10, 2022

Is your feature request related to a problem? Please describe.

<PrismicLink> accepts a Prismic Link field and renders an appropriate link element. If the Link field is empty or is null, <PrismicLink> renders null.

<PrismicLink>'s empty field handling can be difficult to debug when an invalid value is provided. It currently "fails" silently since the component treats an empty or nonexistant value is "empty." An invalid value may be provided if Route Resolver or Link Resolver is not set up properly, or the wrong type of data is provided.

Describe the solution you'd like

<PrismicLink> could implement one or more of the following techniques:

Warn when a filled Link field is provided without a Link Resolver or url property.

A Link field can be one of the following types:

type Link =
  | null
  | {
      type: "Any";
    }
  | {
      type: "Document";
      // document-specific properties
    }
  | {
      type: "Media";
      // media-specific properties
    }
  | {
      type: "Web";
      // web-specific properties
    };

If the field contains type: Document but does not have a url property, we know Route Resolver was not configured. If the url property is missing and we don't have a Link Resolver, we also know Link Resolver was not configured.

In that case, we can print a warning to the console with instructions on how to solve the issue and possible causes.

Describe alternatives you've considered

Provide a fallback prop

If a field is empty, we can render a fallback value. This is equivalent to using @prismicio/helper's isFilled.link() helper directly, but through a React API.

Using the fallback prop would help developers know that the field was treated as empty, helping them better understand the data that was passed in.

<PrismicLink
  field={page.data.myLinkField}
  fallback={<span className="text-red">A link was not provided</span>}
>
  Click me!
</PrismicLink>

This prop may be useful on its own, outside of this feature request.

Provide an optional prop

If a field is empty, we can throw an error or print a warning to the console. This helps developers immediately know an invalid value was provided. If the component is marked as optional, no error will be thrown or logged. null would be rendered.

<PrismicLink
  field={page.data.myLinkField}
  optional={true}
>
  Click me!
</PrismicLink>

The fallback prop may be a better API than a single-use optional prop. The above described behavior could be accomplished with fallback={null}, which is more explicit.

Additional context

The debugging trouble explained in the intro has been experienced by several developers. It usually comes from misconfiguring @prismicio/client or @prismicio/react. Although it is technically "user error", we can help developers fix the issue by providing a helpful message.

If long-form messaging is helpful, we can add a message to the GitHub repository and link to it via prismic.dev.


Reported by @Duaner

@angeloashmore angeloashmore added the enhancement New feature or request label Nov 10, 2022
@lihbr
Copy link
Member

lihbr commented Nov 12, 2022

LGTM, just a note to put the incentive on the Route Resolver inside the warning message.

Wondering how we could standardize those kinds of behavior/checks across SDKs 🤔 i.e. Should this be part of asLink() for example/instead?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants