Forem: Jepser Bernardino

Structuring React components

Jepser Bernardino — Sun, 31 May 2020 14:58:06 +0000

Folder and files structure is something I have found on the matter of the opinion instead of a thing that rules it all.

Depending of the project there is minimal convention on how components are structured inside a project (spoiler alert, inside /components folder and separation of container/UI components).

This time, I want to go to the space on how to structure a component itself.

I have created an opinion after working with several mid sized code bases.

TL;DR:

component-name/
├── index.js/ts
├── component-name.js/ts
├── styled-components.js/ts
├── component-name.test.js/ts 
├── component-name.mapping.js/ts

Files, camelCase or kebab-case?

I use kebab-case naming style, GitHub by default is case insensitive, that means that changing HolaFolder to holafolder is not an actual change that it will recognise.

Also it's simpler to read by having one character that separates the world instead the cognitive load of capital letters vs lowercase ones.

The index file

This is the file that I use to expose the component.

Let's imagine that I have simple UI component that exports default.

// index.js/ts
export { default } from './example-component'

Or in the case of named exports:

// index.js/ts
export { openModal, closeModal } from './example-component'

We don't need to change the imports of any component in which we use the 'example-component'.

Implementation details, in the component-name.js/ts file

I have seen a lot a structure like this:

component-name/
├── index.js

In which index.js has the implementation details of our component, the problem. While working and having 10+ tabs with the same name makes difficult to follow the file that I want to find.

For that reason I add the implementation on a file with the same name as the components' folder, to make easier to work with multiple files.

styled-components.js/ts

This is based on the fact that the last 3 years of my career I have been working in companies that used it.

Having a separated file for the components which responsibility is purely aesthetics make easier for:

A designer that codes to tweak the components without the need to change the implementation file
A developer to separate the concern of your components
Insolate styles in a common pattern file which makes it easier to identify project wide

Tests

Having component-name.test.js/ts is a common pattern, the difference is that I prefer to have the tests as close as the implementation, this so if the component is obsolete and we need to remove it, we remove it as a module, the contrary of having a special folder tree for tests, which can lead to broken (unused files).

Mapping and (component-name.***.js/ts)

Redux is a common library used for state management, but nowadays we have different solutions, and what we do is to "connect", or "map" certain props in our component to a store.

For that reason we created the component-name.mapping.js/ts component.

// mapping component
const mapStateToProps = () => {}
const mapDispatchToProps = () => {}

export default connect(mapStateToProps, mapDispatchToProps)(Component)

In that sense if we have a component that in the future needs to be connected and we have the index.js file that exposes our component, then is as easy to change it to:

export { default } from './component-name.mapping'

And not other components need to be changed.

Wrapping up

index.js/ts: to expose the component
component-name.js/ts: components implementation
styled-components.js/ts: styled component (thanks capitan obvious)
component-name.test.js/ts: tests
component-name.mapping.js/ts: HOC or implementation to connect a component to a store

Hello Treacker, a tracking library for React

Jepser Bernardino — Sun, 10 Nov 2019 20:10:46 +0000

TL;DR:

I built a small (1.5kb) and performant event tracking library, that lets you connect with any tracking provider (GA, MixPanel, etc) with its simple API.

Demo: https://codesandbox.io/embed/sharp-rain-jr0m6?fontsize=14
Library: https://www.npmjs.com/package/treacker
Docs: https://github.com/Badiapp/treacker

Why another tracking library

Tracking solutions like React tracker or React tracking solve the tracking the challenge coming for a perspective that data is present at the moment the tracking event is being triggered, meaning that the data needed to track an event is available from time 0.

Which in reality it's not. Let's see the following example:

const Component = ({ userId, roomId }) => {
  const tracking = useTracking()
  useEffect(() => {
    tracking.trackEvent({ action: 'invite_sent', userId, roomId })
  }, [])

  // the rest of my component
}

But, what if because of the architecture of the application, the asynchronous nature of nowadays applications (or any other reason)the userId or roomId values are not available when mounting the component, the tracking event won't report the correct data.

Having a condition could fix the problem:

const Component = ({ userId, roomId }) => {
  const tracking = useTracking()
  useEffect(() => {
    if(!userId || !roomId) return
    tracking.trackEvent({ action: 'invite_sent', userId, roomId })
  }, [userId, roomId])

  // the rest of my component
}

But I will need to do this do it over and over across the application, this starts to be unmaintainable and too verbose. Instead, what if there could be a way to let the "tracking system" manage that for us, what if the data integrity is part of the responsibilities of this "tracking system".

The proposal

I want to create a tool that:

Works with vanilla JS and React is just an abstraction, so it's not dependant of React architecture constraints.
Its responsibility is to ensure the tracking data integrity
Provides a declarative interface
It is agnostic of the transport service is used on the project to track the events
Has a simple, yet powerful interface

Say hello to Treacker

(Tracking + React) = Treacker 🤯

Treacker takes the following assumptions on the application architecture:

The part of the code in which the "tracking provider" is declared knows about the base data that will need to be tracked (ex. userId, userRole, appVersion), let's say, the global/high-level data

Said that let's see how it works:

Declare a TrackingProvider
Everything you want to track should be inside the Provider tree
Access the provider either using TrackingContext or useTracking hook

Demo

Example

I have will request getRooms and received as a list rooms as props, in which I will track the mounting of each room on the list
I have a component that will show info on a user called UserComponent that will be shown after doing a request to the server in which I will track when mounting

import { useState, useEffect } from 'react'
import { TrackingProvider } from 'treacker'

import UserComponent from './user-component'
import Room from './room'

const INITIAL_PARAMS = {
  locale: 'en',
  app_version: 1
}

const handleOnTrackingEvent = event => {
  // do stuff when the event has been fired.
  // like reporting to Google Analytics or Mixpanel
  // signature { eventName, params, timestamp }
}

const Layout = ({ getUser, getRoom, rooms }) => {

  const [ready, setReady] = useState(false)
  const [params, setParams] = useState(INITIAL_PARAMS)
  useEffect(() => {
    getUser().then((user) => {
      // update the parameters for the provider
      setParams(state => ({
        ...state,
        userRole: user.role,
        userId: user.id,
      })
      setReady(true)
    })

    getRoom()
  }, [])
  return (
    <TrackingProvider params={params} onTrackingEvent={handleOnTrackingEvent} isReady={ready}>
      <UserComponent {...user} />
      {
        rooms.map(room => <Room {...room} />)
      }
    </TrackingProvider>
  )
}

The UserComponent:

import { useEffect } from 'react'
import { useTracking } from 'treacker'

const UserComponent = () => {
  const tracking = useTracking()
  useEffect(() => {
    tracking.track('user-component.loaded')
  }, [])

  return (
    // ... the component implementation
  )
}

Then the room component:

import { useEffect } from 'react'
import { useTracking } from 'treacker'

const Room = ({ roomId }) => {
  const tracking = useTracking()
  useEffect(() => {
    tracking.track('room.loaded', { roomId })
  }, [])

  return (
    // ... the component implementation
  )
}

So what's happening here?

TrackingProvider has 3 main props:
onTrackingEvent, which will be invoked each time there is a tracking event
params, this is going to be the global parameters that will be sent with each event
isReady is the flag that will let know when it's "safe" to dispatch the events

For more info on how the event signature looks like, check the docs.

Even if the data is not ready, for example like UserComponent that mounts before fetching the userData, the events stay in a queue and are dispatched only after knowing that is safe by the isReady flag on TrackingProvider.

More about the interface

withTracking

The library exposes also a HOC withTracking which is useful when the component is not part of the TrackingProvider tree.

registering listeners

In case you need to register more event listeners to the trackingProvider, it's possible using registerListener.

Final words

I found the approach to be useful in my use case and that's why I thought to share it, hopefully it will be useful for you too!

Check the docs for more details, or the demo in codesandbox.

Automating React components creation, say hi to`mkcomponent`

Jepser Bernardino — Sat, 12 Oct 2019 14:22:47 +0000

I am a fan of automating trivial tasks when possible, this allows me to focus on the things that really matter, the linter is a good example of not having to think about a semicolon or unused variables because the machine has a better understanding of the resources used in my program.

While at Typeform, a colleague created a simple CLI tool to create React components, and for me was a great idea, around 15 Frontend engineers didn't have to think about how we created components at the company, because the tool created the folder structure, and the component with the style we had at the company.

The time I decided to create one

Because it was a private project I couldn't port it when I changed to Badi, and I thought it was a great idea to create a CLI tool because it will help me and I will learn how to create a REPL using node.

Requirements

Intuitive (options that are easy to remember)
Can create Function and Class components
Opt-in styled-components and test file
Configurable, using a package.json namespace

The interface

As used when creating a folder using the terminal mkdir, I thought that mkcomponent could be a good option.

The following options are in the first iteration:

Component type: --func, --class, --pure
Help: --help

Allow with some default conventions:

pascal-case for the component name
slug-case for folder and file names

And project-based options:

{
  "mkcomponent": {
    "withTest": false,
    "withStyled": false,
    "testSuffix": "test",
  }
}

The result

I decided to have a simple version I can start using it at badi. If you feel curious to try it, you can find it as react-mkcomponent, and here you can find the repository.

To install yarn global add react-mkcomponent or npm install -g react-mkcomponent
Open the folder you want to create component in and type mkcomponent component-name --func|--class|--pure
Voilà, you have a component!

Making React components responsive with just 2 functions

Jepser Bernardino — Sat, 18 May 2019 16:21:13 +0000

A little bit of context

Recently, I joined Badi as a Frontend Engineer, while working on the main product I found that it uses Bootstrap layout components specifically Row, Col and Container, and those have a props interface that allows you to configure the components by plain properties or object styled properties for each media query available.

import { Col } from 'super-library'

// either like this
<Col md={5} offsetMd={1} />

// or this
<Col md={{ size: 5, offset: 1 }} />

The Frontend team just started working on the components library, which had tokens for the most used components, in my previous experience I found "Layout components" for spacing, alignment and arrangement really useful, so I created two components:

Spacer which was meant to manage spacing in units of 8px to increase design accuracy (inspired on my previous company's design system)
Flex which is a simple implementation around flex layout with some more sauce

const Spacer = ({
  top, left, bottom, right, children,
}) => {
  return (
    <Root
      top={ top }
      left={ left }
      bottom={ bottom }
      right={ right }
    >
      {children}
    </Root>
  );
};

const Root = styled.div`
$({
  top, left, right, bottom,
}) => css`
  margin-top: ${top ? unitizedPx(top) : null};
  margin-right: ${right ? unitizedPx(right) : null};
  margin-bottom: ${bottom ? unitizedPx(bottom) : null};
  margin-left: ${left ? unitizedPx(left) : null};
 `
`;

And we were happy, at this time we were moving from CSS modules to styled-components so instead of having the repeated flex and spacing styling properties we used descriptive components that let us be faster and have less detail overhead because the well-tested components were in charge of that.

The challenge

So far all good, until we had a list of elements that had different layout and spacing depending on the viewport. The fastest thing was to use our MatchMedia component, which uses render props pattern to show one or the other component on mount.

<MatchMedia query={BREAKPOINTS.md}>
  { matches => matches ? <UseThis /> : <UseOther /> }
</MatchMedia>

Since this component was only rendered after a call to the API, the flash of the wrong component wasn't an issue.

But we could do better.

Solution(ish)

Remember the Bootstrap approach? The team was already familiar with that interface and we already were using our enum of media queries, so why not tie this implementation into Spacer and Flex components?

So, the spacer would look something like this:

// for base usage
<Spacer bottom={2} left={2}>cool component here</Spacer>

// for responsive usage
<Spacer md={{ bottom: 2, left: 2 }} left={1}>cool component here</Spacer>

Easy no?

const Spacer = ({
  top, left, bottom, right, children, sm, md, sm, lg, xl,
}) => {
  return (
    <Root
      top={ top }
      left={ left }
      bottom={ bottom }
      right={ right }
      sm={sm}
      md={md}
      lg={lg}
      xl={xl}
    >
      {children}
    </Root>
  );
};

const baseStyles = ({
  top, left, right, bottom,
}) => css`
  margin-top: ${top ? unitizedPx(top) : null};
  margin-right: ${right ? unitizedPx(right) : null};
  margin-bottom: ${bottom ? unitizedPx(bottom) : null};
  margin-left: ${left ? unitizedPx(left) : null};
`;

export const Root = styled.div`
  ${
    ({
      top, left, right, bottom, sm, md, lg, xl
    }) => `
      ${baseStyles({ top, left, right, bottom })}
      ${sm && baseStyles(sm)}
      ${md && baseStyles(md)}
      ${lg && baseStyles(lg)}
      ${xl && baseStyles(xl)}
    `
  }
`;

And this will work if the passed props are correctly formatted. But again, we could do better.

The 2 functions

So the implementation above is too verbose and exposes the implementation of our media queries, what if we add another rule, and we have several responsive components, this doesn't scale well.

We knew that:

There will be base props, in the case of the Spacer, [top, right, bottom, left]
There will be media queries with the same shape that will allow more granular control, in our case, we have [sm, md, lg, xl]

We already use media templates utility from Trick and Tips on styled components repository.

So we have our rules like:

const Root = styled.div`
 //...
 ${mediaqueries.md`
  //specific rules for this break point
 `
`

Props validation

We needed to validate the shape of the prop for the responsive conditions so we can assure that we have the expected behaviour, this without adding any dependency, so I came up with this:

/**
 * Generate a valid structure for responsive configuration for a component
 * @param {object} props props received from the component
 * @param {array} baseProps list of props to be validated
 *
 * @returns a structured object with the props for each media query
 */
export const generateResponsiveProps = (props, baseProps) => {
  // from the breakpoints registered check which props exists
  const shapedPropsWithMq = Object.keys(BREAKPOINTS).reduce(
    (responsiveProps, mqName) => {
      const propsForMq = props[mqName];
      if (!propsForMq && typeof propsForMq !== 'object') return responsiveProps;

      // for the props that exists, prepare them with the correct shape
      const shapedProps = baseProps.reduce(
        (propList, prop) => ({
          ...propList,
          [prop]: propsForMq[prop],
        }),
        {}
      );

      return {
        ...responsiveProps,
        [mqName]: shapedProps,
      };
    },
    {}
  );

  return shapedPropsWithMq;
};

This will create an object of responsive props, with null values for the styled components. For example, the Spacer component needs top, right, bottom and right props:

const BASE_PROPS = ['top', 'right', 'bottom', 'left']

// with this component:
<Spacer sm={{ bottom: 1, top: 2 }} md={{ bottom: 2, top: 1 }} sl={{ top: 1 }} />

const responsiveProps = generateResponsiveProps(props, BASE_PROPS)

// will generate this and remove sl because that's not in my media queries

{
  sm: {
    bottom: 1,
    top: 2,
    left: null,
    right: null
  },
  md: {
    bottom: 2,
    top: 1,
    left: null,
    right: null
  }
}

This is useful for the rules that will be passed to the styled component.

Responsive styling

Now that the props are correctly shaped, the next thing will be applying those to the component, for that, I created a helper function that receives the styles function and returns the styling the given props, the styles for each breakpoint defined.

import { css } from 'styled-components'

// this is what you should change if you have different breakpoints
const sizes = {
  giant: 1170,
  desktop: 992,
  tablet: 768,
  phone: 376,
}

// iterate through the sizes and create a media template
export const mediaqueries = Object.keys(sizes).reduce((accumulator, label) => {
  // use em in breakpoints to work properly cross-browser and support users
  // changing their browsers font-size: https://zellwk.com/blog/media-query-units/
  const emSize = sizes[label] / 16
  accumulator[label] = (...args) => css`
    @media (max-width: ${emSize}em) {
      ${css(...args)};
    }
  `
  return accumulator
}, {})

import { mediaqueries } from '../my-path-to-mq'

/**
 * Call the styles factory for with the correct props for each media query
 * @param {function} stylesGenerator function that generates the styles
 *
 * @returns {array} array of styles to be applied for the registered media queries
 */
export const generateResponsiveStyles = stylesGenerator => props =>
  Object.keys(mediaqueries).reduce((rules, mq) => {
    if (!props[mq]) return rules;

    const styles = mediaqueries[mq]`
    ${stylesGenerator(props[mq])}
  `;
    return [...rules, styles];
  }, []);

So finally, the way the styled component will look like this:

// define the styling function
const baseStyles = ({ top, left, right, bottom }) => css`
  margin-top: ${top ? unitizedPx(top) : null};
  margin-right: ${right ? unitizedPx(right) : null};
  margin-bottom: ${bottom ? unitizedPx(bottom) : null};
  margin-left: ${left ? unitizedPx(left) : null};
`;

// define the styling function for the responsive props
const responsiveStyles = generateResponsiveStyles(baseStyles);

export const Root = styled.div`
  ${baseStyles} // the base styles
  ${responsiveStyles} // the responsive styles
}
`;

This allowed us to separate the possible breakpoints from the implementation of the styles for the component, making it flexible to implement to other components and easy to maintain since the media queries declaration is manage separated from the styling ones.

You can find the code example in this codesanbox.

Happy coding. ☕️