[feat] Pull out example app from library codebase

[haworku]

Is your feature request related to a problem? Please describe.

I find that having the example app inside the library codebase makes library maintenance burdensome.

• It increases the load on dependabot.
• It slows our CI and approval workflow. We often have many outstanding PRs for dependencies that are not used in the published library.
• Security alerts are hard to parse. Hard to understand which issues are impacting the library specific code because most are the example app.

I am also not sure we are getting value out of having the example app in the library

• We do not build the example application as part of CI or regularly test it. We currently have an outstanding issue fix: Project's example doesn't seem to compile/run #1931 that reflects this.
• We are not using the example app as a test sandbox. Instead, we rely on Storybook to test changes, which seems to work pretty well. In addition, maintainers prefer to pull the library into live working apps regularly to verify changes during releases (rather than relying on the example app).

At this point, I think we might be better suited pulling the example out into its own repository that can be updated on its own, separate from the @trussworks/react-uswds codebase. It could reference the latest main branch in its package.json.

Describe the solution you'd like

Remove the /example folder with its nested package.json and all depedendencies. Create a new repo for the example app, pointing at our codebase.

Describe alternatives you've considered

• Use existing tools more efficiently. Lean more into yarn workpaces to isolate the two aspects of the codebase better. Start building the example app in CI and deploying it regularly to ensure its working. Move towards updating example app dependencies in large PRs all at once rather than relying on dependabot. Or have a separate CI flow for dependencies inside the example app. We don't need to be running our library visual regression tests (Happo) on example app changes for example. Consider also simplifying the dependencies in the example app, probably this should not be a CRA app.

^ The issue I see with this approach is its a significant lift and I'm not sure that we are getting value out of the example app to merit it. I would love comments on this though, there are likely things that I am missing. Or maybe folks think that separating the app will not help the maintenance of the library.

[brandonlenz]

I'm, personally, very okay with removing the example app from this repo. I think there's enough adoption out there to reference actual examples in the public domain.

Agreed that this will help greatly with the number of dependabot PRs as well, which is a huge plus.

Storybook provides example implementation of individual components well enough for me.

HOWEVER, I do think our docs around implementing the library as a consumer could use another pass to serve as a replacement for one area the example app demonstrated that storybook does not. I think it's needed anyways, since many of us have learned from our experiences importing and using this library since the docs were originally written. (I'm totally fine with that being a separate issue - #2015)

[brandonlenz]

There's some references to the example apps we also need to consider, as they would need to be removed as well, which also provide some clarity into the purpose (and therefore value?) of the example app:

• Contributing.md

  • "Available commands" reference commands for installing/running the example app
  • From "General guidelines":

    Provide thorough documentation (in Storybook and in the example app) so that users can view the components as they render in the UI, the source code required to use them, and specifications such as how props are used, a11y support, and test coverage.

• Faqs.md

  • While I'm not sure how up-to-date our example app is (e.g. Formik, for example, has some really neat hooks, which I personally prefer, that we do not demonstrate in our example app), the following is important to consider (and remove if we remove the example app):

    we have an example app (see /example directory) which shows how to use react-uswds components with other widely used Javascript/React dependencies.

---

Anyways those comments are my 2c 🪙🪙. Would love to see other folk's thoughts!

[suzubara]

it's clear to me that the example app as it stands is more detrimental than it is helpful, on multiple counts: keeping the library repo & dependencies up to date, providing an accurate example for how to use the library, and a sandbox for development. bc of that I don't have an issue with removing it.

I am on the fence about putting it in its own repo, mostly because I do see the pattern of a library repo containing practical examples quite often, and I find it helpful as a consumer of libraries to see how a package's authors expect it to be used. if the example app is in a different repo, I'm not convinced that that will mean anyone uses or updates it any more than they do now. I'm also seeing more often that lib repos scope the actual library source code inside of a /packages dir, probably to help avoid the issues that we've been experiencing. I'm of the opinion that, long term, there's enough JS package/monorepo tooling out there that should help us successfully maintain examples within the same repo as the library itself, but maybe that is an effort best started over from scratch at some point in the future if at all.

finally: this is tangential but my impression is that USWDS is moving into a more modular structure to allow projects to only import the components they need, and if we wanted to think about moving towards more of a monorepo structure that publishes multiple packages that might align more closely. but I realize all of the above are Big Changes and we are operating with basically a skeleton crew, so tldr: I support whatever is easiest for right now.