Documentation: React Gen2 SDK

[jaydubb12]

Describe the bug

The current documentation within the Builder.io site nor the content within the Github README.md effectively provide insight with
respect to how the Builder SDK can be implemented in the following ways...

1. Centralized component vs duplicated code on every page for client & server side components as well as a single reference to the API key vs requiring it on every page (see recommendation below)
   Current State Suggests writing additional 20-30 lines per page file)

2. Server side rendering AND client side rendering examples with annotations on how / when to utilize each. (See recommendation example below)
   

Current State shows server side example in docs within Builder.io website, whereas the client side example is shown ONLY on the Github site

3. Annotations with respect to NextJS and use server or use client designations which are required within the customComponent files and a noted that they cannot be mixed. Therefore there should be a recommendation to have 2 different component sets...client side and server side.

Note, that using the dependency @builder.io/sdk-react-nextjs and the isISR does not seem to be enough to drive the distinction during compilation...and given there is no issue with OOTB components, it makes me think the key difference is the components that are provided OOTB are pure React components, and given they are not transpiled by NextJS during build time...there is nothing to cause the error that I am seeing when I compile them locally via NextJS.

This makes me think then that a monorepo with vite may be ideal to develop the components then import them into the project will allow me / others to overcome the compilation issue.

Current State use of the server side Builder component will throw a compilation error in the event that a customComponent which is registered is a client-side component which is being utilized on page with the server side delivery of content.

4. Variable urlPath cannot easily be parameterized in the same fashion as model. Given a common model can be used which can have a differentiated path, it is recommended to add urlPath as an independent param / type vs nesting under userAttributes
   

5. Examples provided within Github / NPM do not link to documentation, examples nor resources that will provide developers all of the options that can be passed / utilized with fetchOnentry

Current State documentation is provided via the following link on the Builder.io webiste, but is NOT linked to within the Gen2 references on the Builder.io website, nor is it included in the documentation via README.md which are published within Github / NPM website - (https://www.builder.io/c/docs/content-component)

6. Documentation within Builder.io website which intends to cover the use of the Gen2 content API shows utilization of content={contentJson} which does not match the other published examples, and will likely result in confusion - (https://www.builder.io/c/docs/content-component). Everywhere else in the documentation the content is set as a variable and is not set as contentJson

7. Link within documentation does not make sense, as it routes to the legacy API which is different than the Gen2 content API (https://www.builder.io/c/docs/content-api)
   Legacy Copy "For more information, visit Content API."

8. On this page the Gen2 React component is NOT shown as the recommended approach. Is this dated content, or is the Gen2 approach still NOT considered stable / recommended? (https://www.builder.io/c/docs/sdk-comparison)

9. The 2 Published approaches to consuming data via the Gen2 SDK are inconsistent (see screenshot). Recommend more consistent / comprehensive examples as these introduce more confusion than help.
   

10. The published approach to retrieving data for the Gen2 SDK references the "@builder.io/sdk-react/edge" dependency but the differentiated use of this dependency vs the base dependency is not clear where the use of this dependency vs is recommended vs required to use in place of "@builder.io/sdk-react"

Expected behavior

1. Provide guidance on how to setup / utilize a centralized instance of a server or client component to promote DRY (Do not repeat yourself) principles.

Examples

See examples provided and utilized in sample repo - https://github.com/jaydubb12/nextjs-14-with-builder

• Client Side Centralized Components
• Server Side Centralized Components

Note, for this to work in an ideal world, there will need to be a way to parameterize and send the URL as a param, which is not implemented in this example

Screenshots

See above

Additional context

The guidance, user provided examples, and commentary provided herein is specific to NextJS v13.5 + utilizing app router

[jaydubb12]

@omspacecode looping you in to this ticket related to documentation

[leandrosimoes]

I'm starting to think Builder.io SDK Gen2 does not work with NextJS 13+ using App Router. We are not asking too much here, we just need a working example or guidance on setting up a basic app using this stack but this issue is still open after months.

[samijaber]

We are regularly iterating and improving our documentation, specially concerning the React Gen2 SDK. We have made improvements based off of these pointers from @jaydubb12 and will continue to do so. 🙏🏽

I must note that the Builder Gen2 React SDK is fully working with NextJS App Router. If you follow the instructions here and select React, NextJS App and Gen 2, you should have a fully functioning app.

If you want working examples:

• React Gen2 SDK (NextJS Pages): https://github.com/BuilderIO/builder/tree/main/examples/nextjs-pages-dir-v2
• React Gen2 SDK (NextJS App): https://github.com/BuilderIO/builder/tree/main/examples/nextjs-app-dir-v2
• NextJS Gen2 SDK (NextJS App): https://github.com/BuilderIO/builder/tree/main/examples/next-js-sdk-gen-2-experimental-app-directory

NOTE: If you are trying to register RSCs (React Server Components) as custom components for Builder, then that requires the special (and beta) NextJS SDK. The reasons for a separate SDK are outlined here: https://github.com/BuilderIO/builder/tree/main/packages/sdks/output/nextjs#when-should-i-use-this-sdk-please-read-carefully

@jaydubb12 You mention:

Annotations with respect to NextJS and use server or use client designations which are required within the customComponent files and a noted that they cannot be mixed. Therefore there should be a recommendation to have 2 different component sets...client side and server side.

You should not need separate client-side and server-side implementations to run the React SDK in NextJS. Can you outline the exact issue you encountered that made you think this?