💬 RFC: Component Composability in Frontend Plugins #16876

benjdlambert · 2023-03-15T14:27:04Z

🔖 Need

This RFC is designed to address the topic of being able to configure / replace components deeply nested inside plugins without the additions of props to a public facing component that gets drilled all the way down to where it needs to be.

There's been a few issues and PR's that have popped up that have tried to capture this need like #11819 and #11404, and it might be that one of these ways are what we want to achieve but let's try and collect it all here to come up with a standard or a new system for doing this.

The problem

As the amount of adoption grows, so does requirements for different plugins to do different things, and this sometimes exceeds the capabilities of what the plugin does today. Let's take a few examples from the last few weeks

The list goes on, but the story is the same, contributors want to be able to replace components deeply nested in plugins that aren't accessible to them.

Our solution until this point has been to provide an API for developers to customise these components using props in React components. This then leads to pollution of the API surface for these props.

Let's take a look at the @backstage/plugin-scaffolder Router component, you have these props which all do replacing of some content or component inside the plugin:

export type RouterProps = {
  // This replaces components deep inside the plugin
  components?: {
    ReviewStepComponent?: ComponentType<ReviewStepProps>;
    TemplateCardComponent?:
      | ComponentType<{
          template: TemplateEntityV1beta3;
        }>
      | undefined;
    TaskPageComponent?: ComponentType<{}>;
  };
  groups?: Array<{
    title?: React_2.ReactNode;
    filter: (entity: Entity) => boolean;
  }>;
  // This replaces some Text Component
  defaultPreviewTemplate?: string;
  // This also replaces some Components or Text inside the headers
  headerOptions?: {
    pageTitleOverride?: string;
    title?: string;
    subtitle?: string;
  };
  contextMenu?: {
    editor?: boolean;
    actions?: boolean;
  };
};

Let's take a different plugin, let's take some of the @backstage/plugin-catalog API surface. This plugin is basically engineered for composability in the first place, so that you can provide you own EntityPage component to drive your Entity views inside Backstage. There was an entire epic around Composability specifically around the Widgets and Cards for the Catalog plugin #1536, but as the needs grow, so does the API surface.

export interface EntityLayoutProps {
  children?: React_2.ReactNode;
  // Here's a component that gets replaced
  NotFoundComponent?: React_2.ReactNode;
  // Here's something to show and hide different options
  UNSTABLE_contextMenuOptions?: EntityContextMenuOptions;
  // Here's something to provide additional items
  UNSTABLE_extraContextMenuItems?: ExtraContextMenuItem[];
}

It could be argued that the UNSTABLE_* API's from the EntityLayoutProps could be solved differently by using #11404 to be able to configure new options, but I'm also highlighting the fact that we don't have a standard for what is a prop and what is not.

These additions of props to override components or text deep inside components promotes propdrilling and messy code of passing components through components and bloats the API surface, making evolvability and maintainability harder in the long run.

🎉 Proposal

I want to preface this by saying 🤷 I don't think we know what this looks like yet, and we want to explore along with the community some form of solution or standard to help us clarify the approach.

From looking through the codebase and some of the requests that we get for customisation, it's simple things like text overrides, to more complex things like replacing entire components with something more custom.

I think that the text example is quite interesting, as #4454 could be a part solution for this. i18n in general is something that would allow us to provide default strings, that you could override with your own locale which could replace the text contents of the things that you're trying to configure or override.

The Component approach is something that's a little more difficult. There's some approaches from other projects like Docusaurus using swizzling, there's also approaches like Adaptable Components #11819, or there could be something entirely new that we come up with here.

The text was updated successfully, but these errors were encountered:

padupe · 2023-03-17T13:52:07Z

@angeliski Your initial proposal has been referenced.
How much can we, as a local community (Brazil), corroborate?

angeliski · 2023-03-20T13:30:26Z

Hi, @padupe I am trying to get back in this RFC but other priorities are blocking me.

I think you can try to solve those points in this comment.

I started to experiment a little with lazy loading translations but I didn't do enough to get a good result yet.

antoniobergas · 2023-04-05T06:33:04Z

Hi! Just wanted to keep an eye on this RFC, also we did some first few steps to this direction in the Playlist plugin
#16955

github-actions · 2023-06-04T06:36:35Z