Primer Brand components & React Server Components

[sergioalvz]

Hi everyone! 👋 These last few days I've been playing around with Next.js App Router, which uses React Server Components (RSC) by default, and found out that server-side rendering breaks when including Primer Brand components.

I'm using this discussion to share a few learnings with the team to see if we can eventually make Primer Brand become RSC-friendly 🙌 (we use Next.js to power resources.github.com and are thinking on gradually migrate the application to this new paradigm).

[sergioalvz]

This is an example of how Next.js fails to render Primer Brand components using RSC:

@/app/page.tsx

import {Hero} from '@primer/react-brand';

export default function Home() {
  return (
    <main>
      <Hero>
        <Hero.Heading>Hola</Hero.Heading>
      </Hero>
    </main>
  )
}

The only solution I found to make them work was creating wrapping components that use the new "use client;" directive, which I think makes these components to be hydrated on the client.

@/components/Hero/index.ts

'use client';

import {Hero as PrimerBrandHero} from '@primer/react-brand';

export function Hero({heading}: {heading: string}) {
  return (
    <PrimerBrandHero>
      <PrimerBrandHero.Heading>{heading}</PrimerBrandHero.Heading>
    </PrimerBrandHero>
  )
}

@/app/page.tsx

import {Hero} from '@/components/Hero';

export default function Home() {
  return (
    <main>
      <Hero heading="Hola" />
    </main>
  )
}

I tried to implement a simpler approach, but then I learned that using subcomponents isn't supported in server components:

@/components/Hero/index.ts

'use client';

export {Hero} from '@primer/react-brand';

This is a painful limitation since Primer Brand uses compound components extensively.

[rezrah]

👋 Thanks for opening this discussion @sergioalvz

I think we have a few options here:

1. Add use-client directives to specific components

We can add the use client directives to any component that:

a) Depends on and/or causes a DOM side effect internally
b) Uses functional dot notation in its API

Typically applies to compound patterns, rather than low-level primitive components.

✅ Hero, FAQ, AnchorNav will be affected
❌ Heading, Text, InlineLink won't be affected

Doing this will ensure that those components that are safe to render on a server, can do so and be removed safely from the client bundle.

2. Add additional exports to all compound components

This will allow similar flexibility in the composition of components, but without using functional dot-notation. All affected components would need refactoring to ensure backwards compatibility and interop between the two approaches.

Example:

Before	After
import {Hero} from "@primer/react-brand" <Hero> <Hero.Heading /> <Hero.Description /> </Hero>	import {Hero,HeroHeading, HeroDescription} from "@primer/react-brand" <Hero> <HeroHeading /> <HeroDescription /> </Hero>

Possibly some more options to consider, I'll bring this topic up with the other maintainers. In the meantime, let me know if you have any concerns about the above suggestions.