Stupic - A FE code convention set

Looks like stupid, aha? It comes from an ancient Chinese saying: 'Great wisdom looks stupid. Great skill seems clumsy.'.
It's also a combination of several files types of the core code convention Folder as Component of this convention set, which are Style, Type, hoo(U)k, Props-renderer, Index and Constant.

Folder as component

Click to read more about the thoughts behind folder-as-component.

S.tyled components are different

Separate file to separate code for html dom tree and css dom tree

// Good
// styled.Component.ts
export const Component = styled.div`

`;

export const SubComponent = styled.div`

`;

// Component.ts
import * as S from './styled.Component';
<S.Component>
  <S.SubComponent />
</S.Component>

// Bad
// Component.ts
const SubComponent = styled.div`

`;

const Component = styled(({ className }) => {
  return (
    <div className={className}>
      <SubComponent />
    </div>
  )
})`

`;

Consistant root component name with the component, no need to make up names.

// Good
// Component.ts
const Component = () => (
  <S.Component>
  </S.Component>
);

// Bad
// Component.ts
const Component = () => (
  <S.ComponentContainer>
  </S.ComponentContainer>
);

Clear difference between styled and other components.

// Good
// styled.Component.ts
export const Component = styled.div`

`;

export const Header = styled.div`

`;

export const Content = styled.div`

`;

export const Footer = styled.div`

`;

// Component.ts
import * as S from './styled.Component';

<S.Component>
  <S.Header>
    <OtherComponentA />
  </S.Header>
  <S.Content>
    <OtherComponentB />
  </S.Content>
  <S.Footer>
    <OtherComponentC />
  </S.Footer>
</S.Component>

// Bad
// Component.ts
import { ComponentContainer, Header, Content, Footer } from './styled.Component';

export const Component = () => (
  <ComponentContainer>
    <Header>
      <OtherComponentA />
    </Header>
    <Content>
      <OtherComponentB />
    </Content>
    <Footer>
      <OtherComponentC />
    </Footer>
  </ComponentContainer>
)

No need to add a styled-components for every dom level.

// Good
// styled.Component.ts
export const Component = styled.div`
  .Component-header {
    
  }

  .override-other-component {

  }
`;

// Component.ts
import * as S from './styled.Component';

<S.Component>
  <div className="Component-header">header</div>
  <OtherComponent className="override-other-component" />
</S.Component>

// Bad
// styled.Component.ts
export const Component = styled.div`

`;

export const Header = style.div`

`

export const StyledOtherComponent = styled(OtherComponent)`

`;

// Component.ts
<S.Component>
  <S.Header>header</S.Header>
  <S.StyledOtherComponent />
</s.Component>

Add individual styled-component for reusable, complex or portal components.

// Good
// styled.Component.ts
export const Component = styled.div`
`;

export const ReusableComponent = styled.div`

`;

export const ComplexComponent = styled.div`
  /* Many complex css. */
`;

export const PortalComponent = styled.div`

`;

// Component.ts
import * as S from './styled.Component';

<S.Component>
  <S.ReusableComponent />
  <S.ComplexComponent />

  <Modal>
    <S.PortalComponent />
  </Modal>
</S.Component>

// Bad
// styled.Component.ts
export const Component = styled.div`
  .reusable-component {

  }

  .complex-component {

  }

  .portal-component {

  }
`;

// Component.ts
<S.Component>
  <div className="reusable-component" />
  <div className="complex-component" />

  <Modal>
    {/* Only works when Modal in not implemented by React Portal */}
    <PortalComponent className="portal-component" />
  </Modal>
</S.Component>

// OtherParentComponent.ts
<S.OtherParentComponent>
  <S.Component>
    {/* Use className to reuse the style */}
    <div className="reusable-component" />
  </S.Component>>
</S.OtherParentComponent>

Use hook to handle logic

Use a separate hook file when changing states can be merged

// Good
// useComponent.ts
const useComponent = (props) => {
  const res1 = useSomeHook();
  const res2 = useAnotherHook();

  const loading = res1.loading || res2.loading;
  const error = res1.error || res2.error;
  const data = useMemo(() => ({
    data1: res1.data,
    data2: res2.data,
  }), [res1, res2]);

  return {
    loading,
    error,
    data,
  };
}

// Component.ts
const Component = (props) => {
  const { loading, error, data } = useComponent(props);

  return (
    <S.Component>
      // Render with loading, error and data
    </S.Component>
  );
}

// Bad
const Component = (props) => {
  const res1 = useSomeHook();
  const res2 = useAnotherHook();
  
  const loading = res1.loading || res2.loading;
  const error = res1.error || res2.error;
  const data = useMemo(() => ({
    data1: res1.data,
    data2: res2.data,
  }), [res1, res2]);

  return (
    <S.Component>
      // Render with loading, error and data
    </S.Component>
  );
}

Don't use a separate hook file when hooks are very simple

// Good
// Component.ts
const Component = () => {
  const [open, setOpen] = useState(false);

  return (
    <S.Component>
      <button onClick={() => setOpen(!open)}>toggle open</button>
    </S.Component>
  );
}

// Bad
// useComponent.ts
const useComponent = () => {
  const [open, setOpen] = useState(false);

  const toggleOpen = useCallback(() => {
    setOpen(!open);
  }, [open]);

  return {
    open,
    toggleOpen,
  }
}

// Component.ts
const Component = () => {
  const { open, toggleOpen } = useComponent();

  return (
    <S.Component>
      <button onClick={toggleOpen}>toggle open</button>
    </S.Component>
  );
}

Types should not cut off code

Extract out complex types to keep the main code consistant and meaningful

// Good
// types.Component.ts
export interface Props {
  id?: number,
}

export interface HookProps {
  loading: boolean;
  data: {
    id: number;
    name: string;
  }
}

// Component.ts
import { Props, HookProps } from './types.Component';

const ComponentRenderer: React.FC<Props & HookProps> = React.memo((props) => {
  
});

// useComponent.ts
const useComponent = (props: Props): HookProps => {

}

// Bad
interface Props {
  id?: number,
}

const ComponentRenderer: React.FC<Props & {
  loading: boolean;
  data: {
    id: number;
    name: string;
  }
}> = React.memo((props) => {
  
});

// useComponent.ts
const useComponent = (props: Props) => {
  return {
    id,
    data,
  }
}

Typerify input(props), output(hook props, html dome tree) and side effects(user input and api call), leave the rest auto inferred.

// Good
// types.Component.ts

// input of component and hook
interface Props {}
// output of hook, input of renderer
interface HookProps {
  onClick: () => void;
}
// user input side effect
interface FormValues {}
// api call side effect
interface Resource {}
interface ApiData<T> {}
interface ApiError<T> {}

const apiCall = async (values: FormValues): Resource => {
  
}

<Form
  onSubmit={async (values: FormValues) => {
    // Got a resource with type Resource.
    const resource = await apiCall(values);
  }}
>

// Bad
const a: number = 3;

const apiCall = async (values) => {};

<Form
  onSubmit={async (values) => {
    // Force the resource to be type Resource
    const resource: Resource = (await apiCall(values)) as Resource;
  }}
>

interface UseComponent {
  (props: Props) => {
    onClick: () => void;
  }
}

interface OnClick {
  (e: Event) => void;
}

Constants can be long and sensitive to react components

Declare constants outside component if possible.

// Good
// Object reference not changed
const pageMeta = {

}

const Component = () => (
  <SomeComponent pageMeta={pageMeta}>
);

// Bad
const Component = () => {
  // New object reference every time when Component renders.
  const pageMeta = {

  };

  return (
    <SomeComponent pageMeta={pageMeta}>
  );
};

Declare constants in another file to share them with other files in the component folder.

// Good
// const.Component.ts
export BUTTON_WIDTH = 200;
export PAGE_SIZE = 20;

// Component.ts
import { BUTTON_WIDTH, PAGE_SIZE } from './const.Component';

<S.Button>Fixed Width</S.Button>
{/* Align with button */}
<Box width={BUTTON_WIDTH}></Box>
<Pagination pageSize={PAGE_SIZE} />

// styled.Component.ts
import { BUTTON_WIDTH } from './const.Component';

const Button = styled.button`
  width: ${BUTTON_WIDTH}px;
`;

// useComponent.ts
import { PAGE_SIZE } from './const.Component';
const res = useApi({ pageSize: PAGE_SIZE });

// Bad
// Component.ts
<S.Button>Fixed Width</S.Button>
{/* Align with button */}
<Box width={200}></Box>
<Pagination pageSize={20} />

// styled.Component.ts
const Button = styled.button`
  width: 200px;
`;

// useComponent.ts
const res = useApi({ pageSize: 20 });

Functions are first-class components in JS world

// Good
// const.Component.ts
const createPageMeta = (title: string) => {
  return {
    title: `meta for ${title}`,
  }
}

// Component.ts
const Component = ({ title }) => {
  const pageMeta = useMemo(() => createPageMeta(title), [title]);

  return (
    <SomeComponent pageMeta={pageMeta}>
  );
}

// Bad
// Component.ts
const Component = ({ title }) => {
  // This part can be very long and not really related to the current dom structure.
  const pageMeta = useMemo(() => ({
    title: `meta for ${title}`,
  }), [title]);

  return (
    <SomeComponent pageMeta={pageMeta}>
  );
};

Props Renderer Component is the core

Use a separate renderer when render logic has branches before hooks

// Good
const ComponentRenderer = ({ data }) => {
  const state = useMemo(() => {

  }, [data]);

  return (
    <S.Component>
    </S.Component>
  );
}

const Component = (props) => {
  const { error, loading, data } = useApi();

  if (error) {
    return 'Error!';
  }

  if (loading) {
    return 'Loading...';
  }

  return <ComponentRenderer {...props} data={data} />;
}

// Bad
const Component = (props) => {
  const { error, loading, data } = useApi();
  
  const state = useMemo(() => {

  }, [data]);

  if (error) {
    return 'Error';
  }

  if (loading) {
    return 'Loading...';
  }

  // Can't write it here because of the hook order limitation
  // const state = useMemo(() => {
  // }, [data]);

  return (
    <S.Component>
    </S.Component>
  );
}

Index file re-exports public components & variables

// Good
// Component/index.ts
export { Header as StyledComponentHeader } from './styled.Component';
export { useComponent } from './useComponent';
export { buildResourceAFromResourceB } from './const.Component';
export { ComponentRenderer } from './Component';
export type { Props as ComponentProps } from './types.Component';

// OtherParentComponent.ts
import { StyledComponentHeader, buildResourceAFromResourceB, ComponentRenderer, useComponent, ComponentProps } from 'Component';

<S.OtherParentComponent>
  <StyledComponentHeader>
  </StyledComponentHeader>
</S.OtherParentComponent>

// Bad
// OtherParentComponent.ts
import * as ComopnentS from 'Component/styled.Component';
import { buildResourceAFromResourceB } from 'Component/const.Component';
import { ComponentRenderer } from 'Component/Component';
import { useComponent } from 'Component/useComponent';
import type { Props as ComponentProps } from 'Component/types.Component';

interface Props extends ComponentProps {

}

<S.OtherParentComponent>
  <ComopnentS.Header>
  </ComopnentS.Header>
</S.OtherParentComponent>

Naming

Function/Component name as file name

Use long specific names for components and functions instead of fuzzy names:

# Good
ArticleHeader/ArticleHeader.tsx
useBreakpoints.ts
withDataTable.tsx
parseLink.ts 
mediaUtils.ts

# Bad
ArticleHeader/index.tsx # write component code in index.tsx
article-components.tsx
hooks.ts
hocs.tsx
utils.ts
constants.ts

Resource plus Shape as component name

Use long specific names combining business resource and shape type instead of fuzzy names:

// Good
const ArticleCard = () => <div>...</div>;
const ArticlePage = () => <div>...</div>;
const ArticleBox = () => <div>...</div>;
const ArticleList = () => <div>...</div>;
const ArticleTable = () => <div>...</div>;

// Bad
const Article = () => <div>...</div>;
const ArticleWrapper = () => <div>...</div>;
const ArticleComponent = () => <div>...</div>;
const Component = () => <div>...</div>;

For more shapes, you can refer material-ui components.

Prefer long&consistant names

Long names normally mean clarity and consistancy can improve readibility.

# Good
ArticleCard/index.ts
ArticleCard/ArticleCard.tsx
ArticleCard/ArticleHeader.tsx
QuestionCard/index.ts
QuestionCard/QuestionCard.tsx
QuestionCard/QuestionHeader.tsx

# Bad
ArticleCard/index.tsx
ArticleCard/Card.tsx
ArticleCard/Header.tsx
QuestionCard/index.tsx
QuestionCard/Card.tsx
QuestionCard/Header.tsx

And in files:

// Good
// ArticleCard
const ArticleCard = () => <div>...</div>;
const useArticleCard = () => {};
const buildArticleFromFormValues = () => {};

const ArticleHeader = () => <div>...</div>;
const QuestionCard = () => <div>...</div>;
const QuestionHeader = () => <div>...</div>;

// Bad
const Card = () => <div>...</div>;
const useArticles = () => {};
const formatFormValues = () => {};
const Header = () => <div>...</div>;
// QuestionCard
const Card = () => <div>...</div>;
const Header = () => <div>...</div>;

// Good in ArticleCard/index.ts
export { ArticleHeader } from './ArticleHeader';
export { Props as ArticleCardProps } from './types.ArticleCardProps';

// Bad in ArticleCard/index.ts
export { Header } from './ArticleHeader';
export { Props } from './types.ArticleCardProps';

Shortcuts as words

Although we don't recommend using shortcuts only for shorter names, but when we use them, use them as words:

// Good
import GraphqlJson from 'graphql-type-json';

const buildTocOfCdnUrls = () => {};
const getHtmlFromServer = () => {};
const getHtmlsFromServer = () => {};

// Bad
// From official code example of graphql-type-json
import GraphQLJSON from 'graphql-type-json';

const buildToCofCDNURLs = () => {};
const buildToC_of_CDN_URLs = () => {};
const getHTMLFromServer = () => {};
const getHTMLsFromServer = () => {};

Regularize irregular plural nones

Not all engineers are native English speakers, and we can understand if they are in the wrong foramt as long as it has a necessary s or es suffix. Sometimes, right plural nouns can even cause misunderstandings.

// Good
const articleIndexs = [];
const pageSchemas = [];
const metaDatas = [];
const currencys = [];
const fishes = [];
const analysises = [];

// Bad
const articleIndices = [];
const pageSchema = [];
const metaData = [];
const currencies = [];
const fish = [];
const analyses = [];

// Workaround
const articleIndexList = [];
const pageSchemaList = [];
const metaDataList = [];
const currencyList = [];
const fishList = [];
const analysisList = [];

camelCase for leaf file name

Use camelCase for leaf files(except using ClassCase for Components, as React official recommended):

# Good
article/ArticleGrid/useArticleCard.tsx
// Except for react components
article/ArticleGrid/ArticleCard.tsx

# Bad
article/article-card/article-card.tsx
// Remember we consider folder as component
article/article-card/ArticleCard.tsx

dashed-case for namespace folder name

�Normally, we strongly recommend against using namespaces, but when you need one,

# Good
article-components/ArticleGrid/ArticleCard.tsx
article-utils/groupArticlesByTag.ts
article-types/relatedArticles.ts

# Bad
articleComponents/ArticleGrid/ArticleCard.tsx
// Remember that we consider folder as component, component folder is not a namespace here
article-components/article-card/ArticleCard.tsx

Styling

Order css properties in 3 levels of parent-self-children

When we write a lot of css properties, they could be very hard to read. A small tip is to separate them into 3 sections. 1. css that pair with parent 2. css that control itself 3. css that controls its children

/* Good */
.grand-parent {
  // Control self
  width: 100%;

  // Control children
  position: relative;

  .parent {
    // Pair with parent's parent
    position: absolute;
    top: 0;
    left: 0;
    right: 0;

    // Control self
    color: red;
    background: yellow;

    // Control children
    display: flex;

    .child {
      // Pair with parent
      flex: 1;

      // Control self
      width: 33%;
    }
  }
}

/* Bad */
.grand-parent {
  position: relative;
  width: 100%;

  .parent {
    display: flex;
    position: absolute;
    top: 0;
    color: red;
    left: 0;
    right: 0;
    background: yellow;

    .child {
      width: 33%;
      flex: 1;
    }
  }
}

Use Component name as prefix for public class names

// Good
const ComponentA = styled.div`
  .ComponentA-public-class-name {

  }

  .inner-class-name {

  }
`;

const ComponentB = styled.div`
  .ComponentA-public-class-name {
    // override some css
  }
`;

// Bad
const ComponentA = styled.div`
  .public-class-name {

  }
`;

const ComponentB = styled.div`
  .public-class-name {
    // override some css
  }

  .inner-class-name {
    // override some css
  }
`;

Api

Use Functions/Hooks to fetch data

Api calls are side effects. Manage them with a promise or a meta object and we don't need to know which kind of backend we're using. No matter it's graphql, or fetch or axios or any other libraries.

// Good
const getArticles: Promise<Response<Article[]>> = async (params: ArticlesQueryParams) => {  
  // Build options for api caller
  const options = buildApiOptions(params);

  // Call api with fetch or other api clients. e.g. graphql or axios
  return fetch(options);
}

const useArticles = async (params: ArticlesQueryParams): {
  loading: boolean;
  error: Error;
  response: Response<Article[]>;
  data: Article[];
} => {
  const [loading, setLoading] = useState(false);
  const [response, setResponse] = useState([]);
  const [error, setError] = useState(null);

  const callApi = async () => {
    setLoading(true);
    try {
      const response = await getArticles(params);

      setResponse(response);
    } catch(e) {
      setError(e);
    }
    setLoading(false);
  }

  useEffect(() => {
    callApi();
  }, [callApi]);

  return {
    loading,
    error,
    response,
    data: response.path.to.data,
  }
}

// or with hook libraries
const useArticles = (params: ArticlesQueryParams) => {
  // Build options for api caller
  const options = buildApiOptions(params);

  return useQuery<Response<Article>, Options>(options);
}

// Get type guarded articles in business code with one line code.
import { useArticles } from '@scope/xxx-api';

const Component = () => {
  const { data: articles } = useArticles(params);

}

// Bad
// Import many stuff 
import { Article, ArticleQuery, ArticleResponse } from '@scope/xxx-api';
import { useQuery } from '@apollo/client';
// import { useAxios } from 'axios';

const Component = () => {
  // Write all the states and api calls inside component code. e.g.
  const { loading, data, error } = useQuery<Response<Article>, Options>(options);
}

Use one param as api function input

One param makes refactoring easier and middleware(params builder) easier.

// Good

interface ArticleQueryParams {
  id: string,
+ withAuthor?: boolean,  
}

const useArticle = (params: ArticleQueryParams) => {

};

const articleParamsBuilder = (formValues: FormValues): ArticleQueryParams => {
  return {
    id: formValues.id,
+   withAuthor: formValues.withAuthor,
  }
}

const Component = () => {
  const { data: article } = useArticle(articleParamsBuilder(formValues));
}

// Bad

const useArticle = (
  id: string,
+ withAuthor?: boolean 
) => {
  
};

-const articleParamsBuilder = (formValues: FormValues): string => {
-  return formValues.id;

+const articleParamsBuilder = (formValues: FormValues): [string, boolean] => {
  return [formValues.id, formValues.withAuthor]
}

const Component = () => {
- const { data: article } = useArticle(articleParamsBuilder(formValues));
+ const { data: article } = useArticle(...articleParamsBuilder(formValues));
}

Project Management

Use separate library to mange resource types

// Good
// @scope/xxx-types/src/resources/articles.ts
interface Article {

}

// @scope/fe-app/src/components/ArticlePage.ts
import type { Article } from '@scope/xxx-types';

// @scope/be-app/src/app/article/resolvers/article.resolver.ts
import type { Article } from '@scope/xxx-types';

// Bad
// @scope/fe-app/src/types/graphql/articles
interface FrontendArticle {

}

// @scope/fe-app/src/components/ArticlePage.ts
import type { FrontendArticle } from '../types/graphql/articles';

// @scope/be-app/src/app/article/graphql-types/articles.ts
interface BackendArticle {

}

// @scope/be-app/src/app/article/resolvers/article.resolver.ts
import type { BackendArticle } from '../graphql-types/articles';

Use separate libraries to manage api functions for different backends

// Good
// @scope/xxx-api/src/api-hooks/useArticles.ts
const useArticles = () => {}

// @scope/fe-app-a/src/components/ArticleListPage.ts
import { useArticles } from '@scope/xxx-api';

// @scope/fe-app-b/src/components/ArticleManagementPage.ts
import { useArticles } from '@scope/xxx-api';

// Bad
// @scope/fe-app-a/src/api-hooks/useArticles.ts
const useArticles = () => {}

// @scope/fe-app-a/src/components/ArticleListPage.ts
import { useArticles } from '../api-hooks/useArticles';

// @scope/fe-app-b/src/api-hooks/useArticles.ts
const useArticles = () => {}

// @scope/fe-app-b/src/components/ArticleManagementPage.ts
import { useArticles } from '../api-hooks/useArticles';

Use absolute path for other components

Absolute path means no long or wrong ../s. Also it would be easier to make code work after copying and pasting in another file.

// Good
// Component/Component.ts
import { Button } from '@/components/Button';
import { Typography } from '~components/Typography';
import { Typography } from '@my-org/my-lib/lib/Typography';
import { Icon } from '@my-org/other-lib';

// Bad
// Component/Component.ts
import { Button } from '../Button';
import { Typography } from '../Typography';

Use relative path inside folder components

// Good
// Component/Component.ts
import { Props } from './types.Component';
import { useComponent } from './useComponent';

// Bad
// Component/Component.ts
import { Props } from '@/components/Component/types.Component';
import { useComponent } from '@/components/Component/useComponent';

Use enginner name as prefix of feature/fix branches

Managing branches in monorepo could be very hard, name-prefixed branches would make your life easier.

# Good

$ git branch

  feng/add-component-generator
* feng/fix-custom-env-preview-mode
  feng/fix-image-responsive-bug
  feng/fix-library-babelrc
  feng/fix-section-children-box-shadow
  feng/fix-ssr-className-mismatch-bug
  feng/fix-ssr-className-mismatch-bug-experiment
  feng/fix-ssr-className-mismatch-bug2
  feng/fix-video-url-of-review
  feng/implement-reviews-with-contentful
  feng/responsive-container

# Bad

$ git branch -r 

  origin/tesseract-example
  origin/test
  origin/testa
  origin/testinglib
  origin/tmp-test
  origin/tonygjerry-patch-1
  origin/trav-telematics-limit
  origin/travelers--retention-fix-attempt-3-using-proxy
  origin/tsconfig-correct
  origin/ui-expert-qna
  origin/ui-seo-insurance-e2e
  origin/update-prequal
  origin/update-usdl-regex
  origin/webhook-basic
  origin/wip
  origin/workaround_user_prompt_as_expect_error
  origin/wq-confirm-driver
  origin/wq-estimate-quoting-loader
  origin/wq-state-min-coverage

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Stupic - A FE code convention set

Table of contents

Folder as component

S.tyled components are different

Use hook to handle logic

Types should not cut off code

Constants can be long and sensitive to react components

Props Renderer Component is the core

Index file re-exports public components & variables

Naming

Function/Component name as file name

Resource plus Shape as component name

Prefer long&consistant names

Shortcuts as words

Regularize irregular plural nones

camelCase for leaf file name

dashed-case for namespace folder name

Styling

Order css properties in 3 levels of parent-self-children

Use Component name as prefix for public class names

Api

Use Functions/Hooks to fetch data

Use one param as api function input

Project Management

Use separate library to mange resource types

Use separate libraries to manage api functions for different backends

Use absolute path for other components

Use relative path inside folder components

Use enginner name as prefix of feature/fix branches

Files

README.md

Latest commit

History

README.md

File metadata and controls

Stupic - A FE code convention set

Table of contents

Folder as component

S.tyled components are different

Use hook to handle logic

Types should not cut off code

Constants can be long and sensitive to react components

Props Renderer Component is the core

Index file re-exports public components & variables

Naming

Function/Component name as file name

Resource plus Shape as component name

Prefer long&consistant names

Shortcuts as words

Regularize irregular plural nones

camelCase for leaf file name

dashed-case for namespace folder name

Styling

Order css properties in 3 levels of parent-self-children

Use Component name as prefix for public class names

Api

Use Functions/Hooks to fetch data

Use one param as api function input

Project Management

Use separate library to mange resource types

Use separate libraries to manage api functions for different backends

Use absolute path for other components

Use relative path inside folder components

Use enginner name as prefix of feature/fix branches