Component Best Practices

This guide covers component best practices.

Table of Contents

Code Organization
Organizing Imports
Organizing Exports
We Prefer Functional Components to Class Components
Using and Adding Icons
Debugging Tips
Use React’s FC type as the type for components
Use Next’s Router or Link to navigate between pages

Code Organization

Organizing Imports

For the sake of consistency and readability, imports are ordered as follows:

React
Next
Node
Other 3rd party imports in alphabetical order
Broadleaf libraries (e.g., CommerceSDK)
Newline
Imports from other domains (e.g., @app/common/, @app/product/) and functional classifications (e.g., actions/, hooks/)
- In alphabetical order by domain → then function → then name
- These should always start with the @app/
Newline
Imports from the same functional classification (/hooks) or domain (/product)
- These can use file path shorthand, e.g., ../ for parent directory
Imports from the same module
- These should also use file path shorthand, e.g., ./ for current directory
Newline
Localized messages

We then use alphabetical ordering when importing multiple components/functions from the same dependency: import { get, has, isEmpty, map } from 'lodash';

Example

import { useState } from 'react';
import { useRouter } from 'next';
import type { IncomingMessage } from 'http';
import classNames from 'classnames';
import { get, has, isEmpty, map } from 'lodash';
import { BrowseClient } from '@broadleaf/commerce-browse';

import { Dropdown } from '@app/common/components';
import { useFormatMessage } form '@app/common/hooks';

import Menu from '../Menu';

import messages from './messages';

We also prefer as an import path as possible, usually no more than 3 path segments. This will require that our exports are done correctly.

// this
import { Button, InputField } from '@app/common/components';

// instead of this
import { Button } from '@app/common/components/button';
import { InputField } from '@app/common/components/form/input-field';

Organizing Exports

Our rules for export statements:

Anything that should be exported, whether component, function, type, or constant, should be marked with the export keyword when they are declared rather than after the component or at the bottom of the file, example below.
Functions that should be exported should use the arrow syntax
Only pages should have default exports to keep index.ts files clean, example below
Each module should have an index.ts that has export * from './some-file'; so that all named exports are exported.

component.tsx example

import { FC } from 'react';

import { IMG_NOT_FOUND } from '@app/common/utils';

// exported type
export type Asset = {
  altText: string;
  contentUrl: string;
  tags?: Array<string>;
  title?: string;
  type: string;
};

type Props = {
    asset: Asset;
};

// exported component
export const Asset: FC<Props> = props => {
  const { asset } = props;
  return (
    <img
      alt={asset.altText}
      src={getContentUrl(asset)}
      title={asset.title}
    />
  );
}

// exported function
export const getContentUrl = (asset: Asset): string => {
  return asset.contentUrl || IMG_NOT_FOUND;
}

Corresponding index.ts example

// this exports Asset, Component, and getContentUrl all in one line
export * from './component';

We Prefer Functional Components to Class Components

Functional components take the form of

const Button = ({ label }) => <button type="button">{label}</button>;

Class components take the form of

class Button extends React.Component {
  render() {
    return <button type="button">{label}</button>;
  }
}

Functional components:

let you use the hooks API, which keeps your write cleaner, more readable, and more compact code.
encourage maintaining less state and hooking into the lifecycle API less, which increases reusability
encourage reducing component size and complexity and splitting them into smaller components instead

Also note that the very far-future goal of the React team is deprecate classes altogether—the point being the React team wants you to prefer functional components.

Using and Adding Icons

Available icons are listed in app/common/components/icons.tsx. These are all SVGs and are sourced from https://heroicons.com/. See their site if you want to add a new one; then hover over the icon you want and select "Copy JSX". You can then paste this in app/common/components/icons.tsx and only have some minimal massaging to do to make it uniform with the other icons.

Example icon

export const MenuIcon: FC<IconProps> = ({
  className = 'w-6 h-6',
  stroke = 1,
  ...props
}) => (
  <Svg
    className={className}
    fill="none"
    stroke="currentColor"
    viewBox="0 0 24 24"
    {...props}
  >
    <path
      strokeLinecap="round"
      strokeLinejoin="round"
      strokeWidth={stroke}
      d="M4 6h16M4 12h16M4 18h7"
    />
  </Svg>
);

Tip	Icon size is primarily controlled with the `className` prop, although `stroke` controls the thickness of the vector paths.

Debugging Tips

Use console statements such as console.debug to print data or add debugger; on a line to set a manual breakpoint. The benefit of console.debug over console.log is that we have configured a precommit hook to flag any attempts to commit console.debug. Only use console.log for logs you want in production, not for debugging purposes.

Use React’s FC type as the type for components

Since we’re using Typescript, we need to define the prop and return types. A convenient way to do that for components is to create a custom type for the props then combine that with FC (for FunctionalComponent) on your component definition:

Example icon

import { FC } from 'react';

type IconProps = {
  className?: string;
  stroke?: number;
  title?: string;
}

export const MenuIcon: FC<IconProps> = ({
  className = 'w-6 h-6',
  stroke = 1,
  ...props
}) => (
  <Svg
    className={className}
    fill="none"
    stroke="currentColor"
    viewBox="0 0 24 24"
    {...props}
  >
    <path
      strokeLinecap="round"
      strokeLinejoin="round"
      strokeWidth={stroke}
      d="M4 6h16M4 12h16M4 18h7"
    />
  </Svg>
);

Use Next’s Router or Link to navigate between pages

Next provides a router hook for declaratively navigating between pages hosted by the app, and a Link component instead of a plain <a>.

Important

useRouter provides several callbacks for declarative navigation. However, those methods cannot be called on the server-side. If you need to call them early in the page render like in the example below, make sure the page is not server-side rendered.

Example disabling SSR for a page

import dynamic from 'next/dynamic';

const MyPageComponent = () => {};

export default dynamic(() => Promise.resolve(MyPageComponent), { ssr: false });

Alternatively, try doing the redirect on the server-side without using useRouter.

Example redirect on server-side

import { GetServerSideProps } from 'next';

export default function RedirectingComponent(): JSX.Element {
  return null;
}

export const getServerSideProps: GetServerSideProps = async () => {
  return {
    redirect: {
      destination: '/',
      permanent: false,
    },
  };
};

Example using router

import { FC } from 'react';
import { useRouter } from 'next/router';

export default function SignInOrRegister(): JSX.Element {
  const { replace } = useRouter();

  if (isAuthenticated) {
    replace('/my-account');
    return null;
  }
}

Note	Usually you should use the `Button` component instead, which can dynamically decide between showing a button or a link depending on if a URL is provided. It’s also a bit simpler since you don’t also need to add a `<a>` inside of the `Link`.

Example with Link (some details omitted for brevity)

import Link from 'next/link';
import { get, isEmpty, omit, pick } from 'lodash';

export const Button: FC<ButtonProps> = props => {
  const { children, ...rest } = props;

  if (!isEmpty(get(rest, 'to'))) {
    const linkProps = pick(rest, linkFields);
    const anchorProps = omit(rest, linkFields);
    return (
      <Link {...linkProps} href={linkProps.to}>
        <a {...anchorProps}>{children}</a>
      </Link>
    );
  }

  return <button {...(rest as BtnProps)}>{children}</button>;
};

const linkFields = [
  'to',
  'href',
  'as',
  'replace',
  'scroll',
  'shallow',
  'passHref',
  'prefetch',
  'locale',
];