search

BuilderIO / builder

Visual Development for React, Vue, Svelte, Qwik, and more
https://builder.io
MIT License
7.36k stars 915 forks source link

Documentation: React Gen2 SDK #3359

Open jaydubb12 opened 3 months ago

jaydubb12 commented 3 months ago

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) Screenshot 2024-06-25 at 11 16 54 AM

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

  1. 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.

Screenshot 2024-06-25 at 11 10 49 AM

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.

  1. 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 Screenshot 2024-06-25 at 11 01 53 AM

  2. 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)

Screenshot 2024-06-25 at 10 56 18 AM

  1. 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

Screenshot 2024-06-25 at 10 58 51 AM

  1. 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."

  2. 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)

Screenshot 2024-06-25 at 10 33 38 AM

  1. 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. Screenshot 2024-06-25 at 10 37 18 AM

  2. 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"

Screenshot 2024-06-25 at 10 51 27 AM

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

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 commented 3 months ago

@omspacecode looping you in to this ticket related to documentation