Improve the developer experience when using React

[zemirco]

According to several sources, React is the strongest frontend development framework available.

https://insights.stackoverflow.com/trends?tags=reactjs%2Cangular%2Cangularjs
https://survey.stackoverflow.co/2022/#web-frameworks-and-technologies
https://www.jetbrains.com/lp/devecosystem-2021/javascript/
https://npmtrends.com/@angular/core-vs-react
https://trends.google.com/trends/explore?cat=733&date=today%205-y&q=React,Angular
https://star-history.com/#facebook/react&angular/angular&Date

It would be really nice to have a better developer experience when using Liquid Design Components with React.

Right now the code snippest in your documentation describe how to use the components as web components. I believe it would be beneficial to also include code snippets for React so developers could simply copy&paste them into their own code.

Other component libraries have that feature and it allows for faster integration.

https://mantine.dev/core/button/

import { Button } from '@mantine/core';

function Demo() {
  return (
    <Button>
      Settings
    </Button>
  );
}

https://ant.design/components/button

import { Button } from 'antd';

function Demo() {
  return (
    <Button type="primary">
      Settings
    </Button>
  );
}

https://react.fluentui.dev/?path=/docs/components-button-button--default

import { Button } from '@fluentui/react-components';

function Demo() {
  return (
    <Button appearance="primary">
      Settings
    </Button>
  );
}

Thank you and keep up the great work!

[borisdiakur]

I'm trying to evaluate the options we have for integrating framework specific examples in our documentation. Here is what I have so far:

1. iframe based solution with sandbox service (sandbox embeds) for all examples:
   + comparably small effort
   + user does not need to navigate away from the docs / have another open tab
   + forking and playing with examples is possible
   − tether elements "captured" in iframe
   − sandbox start up time
   − dependency on third party service to display any example
   − examples are located separately from project (async development)
   − no theme switcher

2. iframe based solution with sandbox service (sandbox embeds) for framework specific examples only:
   + comparably small effort
   + forking and playing with examples is possible
   ± examples can be added after actual feature development
   ± sandbox start up time (is less critical than with the pure iframe solution)
   − tether elements "captured" in iframe
   − no theme switcher

3. open in sandbox solution:
   + comparably smallest effort
   + forking and playing with examples is possible
   ± examples can be added after actual feature development
   ± sandbox start up time (is even less critical than with any of the iframe solutions)
   − user needs to navigate away from the docs / have another open tab

4. custom implementation:
   + flexibility (with option to enhance component viewer visually and functionally)
   + user does not need to navigate away from the docs / have another open tab
   + examples can be added during actual feature development
   + theme switcher still works
   − prone to bugs (due to custom code and less encapsulation)
   − comparably huge initial effort plus maintenance effort
   − forking and playing with examples is not possible
   − docs need to load additional framework specific JS code

I tend to go with option 3, because it's the least disruptive one while improving the DX significantly, and allows for quick iterations. Feedback welcome.

[renet]

5. Adding a Storybook at least with framework-specific examples (maybe even for all examples) embedding them may result in an even better DX.
   + playing around with props is very easy with prepared stories.
   + lower effort than solution 4.
   ± little different experience than sandboxes, as code cannot be edited directly.
   ± may work for non-framework-specific examples, as well. but may need separate projects.
   − forking is only possible for the whole Storybook project, not for single examples.
   − comes with the downsides of the other iframe solutions.

With solution 3, do you mean opening only framework specific examples in sandboxes and keeping the non-framework-specific examples as is?

[borisdiakur]

With solution 3, do you mean opening only framework specific examples in sandboxes and keeping the non-framework-specific examples as is?

Yes.

[borisdiakur]

So, I've been playing around with Storybook yesterday.
− The Setup is indeed complex in our case as we'd like to have both, Web Components (and CSS Components) as well as React components running within Storybook (it doesn't make much sense to use separate docs here)
− There is no easy way to use the props documentation feature of Storybook with a generated React component that is imported from our dist directory
− The code displayed in Storybook for an imported React components displays <forwardRef instead of <LdButton (there is a workaround, however it involves manual work for each example in a story)
− Storybook embeds do not support display of the rendered component with an open code viewer and closed toolbar (hacks required)
− iframe hight is unknown / can be dynamic
− we need to build and deploy Storybook plus set up a watcher during development
− dependency / maintenance hell (at least 16 new dependencies) (storybook 7 is coming soon!)

I like the idea itself, but I believe that the actual "cool" feature from Storybook, which is the ability to tweak props and see how the component changes, does not justify the effort. As @toastedtoast pointed out (internal discussion):

How often do we really use this feature ourselves?

The most important feature requested from @zemirco is:

[...] include code snippets for React so developers could simply copy&paste them into their own code.

@toastedtoast also proposed another option:

6. add React code snippets to the code viewer for viewing and copy pasting purposes but render the Web Component instead without using the React bindings.
   + comparably smallest effort (even smaller than with option 3)
   + user does not need to navigate away from the docs / have another open tab
   + no third party service needed
   + examples can be added during actual feature development
   + with can still add option 3 on top at a later point in time
   + no effects on startup time
   − forking and playing with examples is not possible
   − examples must be tested for functionality manually during development (in most cases this is trivial though)

All in all 6. seems to be the most pragmatic solution. We can even make it even more user friendly by moving the Web Component / CSS Component / React Component switch into the code viewer and persisting the user's choice in local storage, so that, after picking a display option, the choice is stored and used across all examples in the docs. React devs will then always see React examples, while non-React devs will see whatever code they chose to see.

[toastedtoast]

− examples must be tested for functionality manually during development (in most cases this is trivial though)

Think it's definitely crucial to make sure that samples are working to prevent a unfortunate surprises or confusion.
Not quite sure if it's straight forward to use some automated tests for it, but in the meantime maybe we setup (or reuse) a react sandbox which we can simply copy and paste code into it to see if the sample works. If we do so, we should make sure to document this process well and should include it in the review process.

[borisdiakur]

I have implemented option 6 in a branch for the button component. This is available on our preview environment. Please have a look and let me know what you think: https://liquid-git-docs-reactexamples-uxsd.vercel.app/components/ld-button/

[borisdiakur]

We've added React code snippets to all component examples. React developers should now feel a little bit more at home when reading the docs. 🚀