Reusable Components Styleguide
Tips and tricks for making components shareable across different projects (framework agnostic).
Components are now the most popular method of developing frontend applications. The popular frameworks and browsers themselves support splitting applications to individual components.
Components let you split your UI into independent, reusable pieces, and think about each piece in isolation.
Why me?
This series summarizes what I have learned in the last months working as head of Developer Experience at Bit. Bit is a components collaboration tool that helps developers build components in different applications and repositories and share them.
During this period, I have seen components developed by many different teams and across different frameworks. The good parts and the bad parts have led me to define some guidelines that can help people build more independent, isolated, and hence reusable components.
Table of Contents
- Reusable Components Styleguide
Directory Structure
One component -> One directory
├── Button.spec.tsx
├── Button.stories.tsx
├── Button.style.tsx
├── Button.tsx
└── __snapshots__
└── Button.spec.tsx.snap
1 directory, 5 files
├── components
│ ├── Button.style.tsx
│ └── Button.tsx
├── stories
│ └── Button.stories.tsx
└── tests
├── Button.spec.tsx
└── __snapshots__
└── Button.spec.tsx.snap
4 directories, 5 files
The component produces creates a directory structure that is easily consumable by placing all the related files together. Having all files located in a single directory makes it easier for component consumers to reason about the items that are interconnected. File references are becoming shorter and easier to find the referenced item. Shorter file references make it easy to move the component to different directories. A typical reference pattern is:
style <- code <- story <- test
The component code is importing the component's style (CSS or JS in CSS style). A story (supporting CSF format) is importing the code to build the story. And the test is importing and instancing a story to validate functionality. (It is also totally ok for the test is directly importing the code).
Use Aliases
import { } from '@utils'
import { } from '../../../src/utils';
paths
mapping to create a mapping to reference components. Rollup uses the @rollup/plugin-alias
for creating similar aliases, and Webpack is using the setting of resolve.alias
for the same purpose.
APIs
Component's APIs are the data attributes it receives and the callbacks it exposes. The general rule is to try and minimize the APIs surface to the necessary minimum. For component producers, this means to prepare the APIs so they are logical and consistent. Component consumers get APIs that are simple to use and reduces the learning curve when using the component.
Use discrete values
type LocationProps = {
position: 'TopLeft' | 'TopRight' | 'BottomLeft' | 'BottomRight'
}
type LocationProps = {
isLeft: string,
isTop: string,
}
Set Defaults
type LocationProps = {
position: 'TopLeft' | 'TopRight' | 'BottomLeft' | 'BottomRight'
}
defaultProps = {
position: 'TopLeft'
}
Setting parameters makes it easy for the consumer to start using the component, rather than find fair values for all parameters. Once incorporating the component, tweaking it to the exact need is more tranquil.
Globals
Do not rely on global variables
export const Card = ({ title, paragraph, someGlobal }: CardProps) =>
<aside>
<h2>{ title }</h2>
<p>
{ paragraph + someGlobal.value }
</p>
</aside>
Components may rely on globals, such as window.someGlobal, assuming that the global variable already exists.
Relying on parameters gives the consuming application greater flexibility in using the components and does not require it to adhere to the same structure that exists in the producing application.
Provide fallbacks to globals
if (typeof window.someGlobal === 'function') {
window.someGlobal()
} else {
// do something else or set the global variable and use it
}
window.someGlobal()
Fallbacks let the consuming application a way to build the application in a manner that is less coupled to the way the provider application. It also does not assumes that the global was set at the time it is consumed.
NPM Packages
Our code relies on third-party libraries for providing specific functionalities, such as scrolling, charting, animations, and more. Third-party libraries are important but take care when adding them.
Ensure versions compatibility
"peerDependencies": { "my-lib": ">=1.0.0" }
"dependencies": { "my-lib": "1.0.0" }
To understand the problem, let's understand how package managers resolve dependencies. Assume we have two libraries with the following package.json files:
{
"name": "library-a",
"version": "1.0.0",
"dependencies": {
"library-b": "^1.0.0",
"library-c": "^1.0.0"
}
}
{
"name": "library-b",
"version": "1.0.0",
"dependencies": {
"library-c": "^2.0.0"
}
}
The resulting node_modules tree will look as follow:
- library-a/
- node_modules/
- library-c/
- package.json <-- library-c@1.0.0
- library-b/
- package.json
- node_modules/
- library-c/
- package.json <-- library-c@2.0.0
You can see that library-c is installed twice with two separate versions. In some cases, such as with React or Angular frameworks, this can even cause errors. However, if the configuration is kept as follow:
{
"name": "library-a",
"version": "1.0.0",
"dependencies": {
"library-b": "^1.0.0",
},
"peerDependencies": {
"library-c": ">=1.0.0"
},
}
{
"name": "library-b",
"version": "1.0.0",
"dependencies": {
"library-c": "^2.0.0"
}
}
library-c is only installed once:
- library-a/
- node_modules/
- library-c/
- package.json <-- library-c2@.0.0
- library-b/
- package.json
Also, make sure the peer dependency has very loose versioning. Why? When installing packages, both NPM and Yarn flatten the dependency tree as much as possible. So let's say we have packages A and B. They both need package C but with different versions — say 1.1.0 and 1.2.0. NPM and Yarn will obey the requirement and install both versions of C under A and B. However, if A and B require C in version ">1.0.0", C is only installed once with the latest version.
Minimize packages
When reusing code, you also need to reuse the packages that use it. Relying on multiple packages makes it hard to move components between applications, but also increase bundle size for all the component consumers.
Styling
By design, CSS is global and cascading without any module system or encapsulation.
Scope styles to component
When reusing components across different apps the application level styles are likely to change. Relying on global styles can break styling. Encapsulating all style inside the component ensures it looks the same even when transported between applications.
Restrict styles with themes
class ThemeProvider extends React.Component {
render() {
return (
<ThemeContext.Provider value={this.props.theme}>
{this.props.children}
</ThemeContext.Provider>
);
}
}
const theme = {
colors: {
primary: "purple",
secondary: "blue",
background: "light-grey",
}
};
Component producer need to control the functionality and the behavior of the component. Reducing the levels of freedom for the components consumers can provide a better predictability to the component's behavior, including its visual appearance.
CSS Variables as theming variables
:root {
--main-bg-color: fuchsia;
}
.button {
background: fuchsia;
background: var(--main-bg-color, fuchsia);
}
CSS variables are framework independent and are supported by the browser. Also, CSS variables provide great flexibility as they can be scoped to different components.
State Management
Components may use state managers such as Redux, MobX, React Context, or VueX. State managers tend to be contextual and global. When reusing components between applications the consuming applications must have the same global context as the original one.
Decouple data and layout
//container component
import React, { useState } from "react";
import { Users } from '@src/presentation/users'
export const UsersContainer = () => {
const [users] = useState([
{ id: "8NaU7k", name: "John" },
{ id: "Wxxfs1", name: "Jane" }
]);
return (
<Users data="users">
);
};
//presentational component
export const Users = (props) => {
return (
<div className="user-list">
<ul>
{props.data.map(user => (
<li key={user.id}>
<p>{user.name}</p>
</li>
))}
</ul>
</div>
);
};
//single component that manages both data and presentation
import React, { useState } from "react";
export const Users = () => {
const [users] = useState([
{ id: "8NaU7k", name: "John" },
{ id: "Wxxfs1", name: "Jane" }
]);
return (
<div className="user-list">
<ul>
{users.map(user => (
<li key={user.id}>
<p>{user.name}</p>
</li>
))}
</ul>
</div>
);
};
Distribution
Package for distribution
# Package.json
"main": "component.cjs.js"
"module": "component.es.js"
"browser": "component.umd.js"
The JS world has a unique trait of a single interpreted language that is running on multiple platforms. Nodejs in various versions and various browsers create a plethora of runtime environments.
Despite a continuous shift towards standard module handling, there are still a variety of methods to handle bundled code.
During this struggling period and until we get one standard to rule them all, we should be good citizens of the JS-universe by feeding each packaging beast with its favorite flavor.
For example, Webpack supports the different fields, according to the target it is building for.
//webpack.config.js
//When the target property is set to webworker, web, or left unspecified:
module.exports = {
//...
resolve: {
mainFields: ['browser', 'module', 'main']
}
};
//For any other target (including node):
module.exports = {
//...
resolve: {
mainFields: ['module', 'main']
}
};