Developer documentation

This component library lives as a combination of NextJS compatible server and client React components. They are written in a combination of typescript and javascript. Typescript is used primarily where types are important, ie, while data fetching and validating. Javascript is preferred when the component needs to just display something without any logic. The only reason for using Javascript in these cases is to reduce the amount of overhead in creating a single display component.

Low level components are components that do not carry opinons about data structures. Often the sections of this design system that are setup under foundations and patterns fall under this low level component library.

CMS aware components on the other hand are tightly coupled to how Agility CMS supplies its data on query.

There are a number of low-level components that are stored in the @boystown/components library (under packages/components). These components are unopinionated about where they are used and set some basic style and design principles (colors, variants, etc.). These components can be used in any React project regardless of the underlying data structures.

Adding a component is as simple as creating a directory for the component, with an index.js|ts file that exports the component. It can then be referenced using the following code

import { NamedComponent } from '@boystown/components/<component_dir>';

All CMS-aware components are stored in the @boystown/website project (under apps/website/src/components). These components use the main component library @boystown/components as building blocks but are aware that the props they are receiving may be coming from Agility CMS.

The codebase contains a number of common hooks and providers used by multiple components, including providers to calculate screen size, providers to handle gestures and search. Please familiarize yourself by looking through the /packages/hooks directory.

A number of helpers exist in the codebase to fetch data. This pattern is highly encouraged as it allows us to use the same fetch patterns universally (on the client and server).

The following outline the recommended workflow for creating new features.

1. Review the component visually and document its props with a designer on the same call. Verbalize how you would like to build this component with its controls.
2. Check if the component has the common patterns of headings content or buttons in it.
3. Check if the component has child lists (think of a component like a Carousel). Make sure you are following appropriate naming conventions.
4. Spend an hour playing with components in the CMS to see if you can achieve the new component with what exists - or even achieve 90% of what you need without new code. Don't be afraid to ask why we need a new component.
5. Model the component in the CMS, ensure your model takes into account any common patterns.
6. Identify the lower level components needed to create your main component. Often this would be headings, actions, taxonomies and more. Make sure you are familiar with the patterns section of this guide.
7. Create a CMS component that simply echoes the props out. Make sure your data is flowing correctly before moving to the front end. Ensure you place a docblock with @params documenting your props in the code.
8. Create your final component. Re review the props in the code.
9. Work with a designer to build a page / section for this new component

1. Review a couple of the files in /packages/lib to understand common patterns for data fetching.
2. If you need to combine more than one data source, think about the tasks and promises that have to be executed.
3. Think about sensible defaults for the data sources and the types of data
4. Write it in typescript only
5. Check your fetch calls both on the client and the server. If they do not work on the client, consider moving the fetch call into a proxy behind an api route.