We follow Airbnb JavaScript Style Guide (https://github.com/airbnb/javascript) and Airbnb React/JSX Style Guide (https://github.com/airbnb/javascript/tree/master/react). This document extends and/or overrides those guides, so it take precedence. We also define some basic rules for Redux and CSS stylings.
our linter packages, their naming style copies the one used by airbnb:
- @innovatrics/eslint-config-innovatrics-typescript
- typescript + react, mostly used for client-side code
- @innovatrics/eslint-config-innovatrics-typescript-base
- typescript, mostly used for server-side code
- @innovatrics/eslint-config-innovatrics
- flow + react, mostly used for client-side code
- @innovatrics/eslint-config-innovatrics-base
- flow, mostly used for server-side code
If a property or variable is a boolean, or function returns boolean, use is, has, can or should prefix. (Accessors - Booleans)
// bad
if (!dragon.age()) {
return false;
}
let good = false;
let sign = false;
let closeDocument = true;
export const updateQuery = function doSomething(createVersion) {}
// good
if (!dragon.hasAge()) {
return false;
}
let isGood = false;
let canSign = false;
let shouldCloseDocument = true;
export const updateQuery = function doSomething(hasToOverwriteVersion) {}To consistently write certain variable names, we use these rules:
- if the name is an acronym, like
URLcomes fromUniform Resource Locator, we write it lowercase when it is alone, and all uppercase when part of a longer name - if the name is an abbreviation of a longer word, like
id(fromidentifier) orsrc(fromsource), we write it lowercase when it is alone, and camel case when part of a longer name
examples:
const url = 'x'const imageURL = 'x'const id = 'x'const imageId = 'x'const src = 'x'const imgSrc = 'x'
Images are in a /img subfolder, has size suffix in its name, and imported into React component as a constant with image type suffix (Png, Svg, Jpg, ...).
// bad
import organization from './organization.png';
import phone from '../../common/phone.svg';
// good
import organizationPng from './img/organization-24x24.png';
import phoneSvg from './img/phone.svg';Correctly setup ID's are essential for proper QA/testing. IDs consist from two parts, {LEFT}-{RIGHT}, where {LEFT} part is the name of the component, and {RIGHT} is any string (words separated with dashes) that makes the whole ID unique. Only {LEFT} part is mandatory.
So for example in our-example.component.jsx file, there is a OurExample React component and every single ID will start with our-example- prefix.
const OurExample = (props) => {
const id = 'our-example';
return (<h1 id={`${id}-heading`}>{props.text}</h1>);
}Redux containers (those React components which use Redux connect() to access state) has Container postfix in its name - for example LoadingScreenContainer is in /loading-screen.container.jsx.
Redux components has no special postfix, not even an Component. Example: IconButton is in /components/buttons/icon-button.component.jsx.
All imports must import components/containers under their original name. (So once full text search is used, it must be simple to find particular component)
// GOOD
import LoadingScreenContainer from './loading-screen.container';
// BAD
import MyVeryCreativeImportName from './loading-screen.container';The handler functions should be named of the form handle*, for example handleClick
or handleStart. When sent as props to a component, the property-keys should
be named of the form on*, for example onClick or onStart.
example:
function Activator(props) {
return <button onClick={this.props.onActivation}>Activate</button>;
}
function Thing(props) {
const [isActive, setActive] = useState(false);
function handleActivation() {
setActive(true);
}
return <div>
Thing is {isActive ? 'Active' : 'Inactive'}
<Activator onActivation={handleActivation}/>
</div>;
}If you need to add flow-types for a third-party (npm) module, use
flow-typed. The files are downloaded into the
flow-typed/npm folder. Commit them into our git-repository.
If the module does not have a type-definition at flow-typed, create the type-definition,
and put it into the flow-typed folder (not into it's npm subfolder). Also, try to
have the type-definition integrated into the flow-typed project. If that happens,
migrate to the file from flow-typed.
You often have to bind react-component-methods in the constructor, like this:
class Thing extends React.Component {
constructor() {
this.handleClick = this.handleClick.bind(this);
}
}
Flow does not handle well these binding approaches, see bug facebook/flow#5874 , we recommend this workaround:
class Thing extends React.Component {
constructor() {
(this:any).handleClick = this.handleClick.bind(this);
}
}
Inspired by this article
There are 3 types of action creators.
- Simple action creator. Returns pure javascript object:
function showSaveDocumentDialog(text: string): Action {
return {
type: actionTypes.SHOW_SAVE_DOCUMENT_DIALOG,
queryText: text
};
}All simple action creators should be described by a single, union type, called Action:
// @flow
export type Action =
{ type: 'SHOW_SAVE_DOCUMENT_DIALOG', queryText: string }
| { type: 'HIDE_SAVE_DOCUMENT_DIALOG' }
| { type: 'MOVE_SAVED_DOCUMENT_REQUEST_SUCCESS', result: { folder_id: number } }
...
;- Thunk action creator. Uses redux-thunk:
function cancelQueryPartialAccessDialog(): ThunkAction {
return (dispatch: Dispatch) => {
dispatch({
type: actionTypes.CANCEL_DOCUMENT_PARTIAL_ACCESS_DIALOG
});
dispatch(hideQueryPartialAccessDialog());
};
} Thunk actions should be described by ThunkAction type:
// @flow
export type ThunkAction = (dispatch: Dispatch, getState?: GetState) => any; We always describe our state. All reducers should have type to avoid a type errors:
type Friend = {
name: string,
};
type FriendsState = {
list: Array<Friend>,
loading: boolean,
};
type AppState = {
isMenuOpen: boolean,
};Examples of incorrect code:
/**
* @flow
*/
import type { FriendState } from '../types';
type State = FriendsState;
const initialState = {
loading: false,
list: null,
};
export function friends(
state: State = initialState,
action: Object
): State {
return state;
}It returns:
src/reducers/friends.js:9
9: list: null,
^^^ null. This type is incompatible with
2: list: Array<{ name: string }>,
^^^^^^^^^^^^^^^^^^^^^ array type. See: src/types.js:2Thanks to Flow and the state having a corresponding type, we were able to catch that tiny mistake as early as it happened.
Examples of correct code:
/**
* @flow
*/
import type { FriendState } from '../types';
type State = FriendsState;
const initialState: State = {
loading: false,
list: [],
};
export function friends(
state: State = initialState,
action: Object
): State {
return state;
}Note: now we use everywhere inexact type definition. It means that flow doesn't complain if some property is not defined in type.
To avoid this problem we should use Exact type:
/**
* @flow
*/
type Exact<T> = T & $Shape<T>;
import type { FriendState } from '../types';
type State = FriendsState;
const initialState: State = {
loading: false,
list: [],
};
export function friends(
state: Exact<State> = initialState,
action: Object
): Exact<State> {
return state;
}We use Exact<T> only in those 2 places in the definition of the reducer function. Exact type can be imported:
import type { Exact } from 'app/types';State of whole application has own type called State. This type should be used when use connect() to map state to props of our containers.
type State = {
friends: FriendsState,
app: AppState,
};/**
* @flow
*/
import { connect } from 'react-redux';
import type { State } from '../types';
export default connect(
(state: State) => ({
list: state.friends.list,
})
)(Container);This pattern helps us to reason about the entire app state as well as eliminate common issues, like misspelling the property names.
Our css classes use in-* naming conventions. Any css class without in- prefix, is a class
from an external css library (Twitter Bootstrap 4 for example). In case the css class is for QA purpose, use in-qa-* convention.
<!-- BAD -->
<div className="modal-body" styleName="modal-body-red">...</div>
<!-- GOOD -->
<div className="modal-body" styleName="in-modal-body">...</div>Use SC suffix for styled components.
const PanelSC = styled.div`
background: blue;
`;
const BarSC = styled.div`
color: red;
`;
const Bar = () => {
// maybe some code here
return (
<BarSC>
<PanelSC>earum nostrum cum</PanelSC>
Aut minima assumenda.
</BarSC>
);
};
export default Bar;Do not export styled components directly (as it has a lot of props), but wrap it into simple React component with fewer props.
const FooterSC = styled.footer`
text-align: center;
`;
const Footer = () => <FooterSC>doloremque quasi similique</FooterSC>;
export default Footer;Project structure is driven by LIFT Principle. Folder structure is organized with approach “folders-by-feature”, not “folders-by-type”
Folders and files are named with all-lowercase, words separated by dash. File name suffix says, what type of code is in the file. Suffix is full stop separated sequence, starting with the more specific identifier, to the less specific ones:
/save-file-dialog
|-- save-file-dialog.actions.js
|-- save-file-dialog.actions.spec.js
|-- save-file-dialog.reducers.js
|-- save-file-dialog.reducers.spec.js
|-- save-file-dialog.component.jsx
|-- save-file-dialog.component.scss
Test file has the same name, as the tested unit, with “.spec.js” suffix. Test file is in the same folder as the tested code.
/save-file-dialog
|-- save-file-dialog.actions.js
|-- save-file-dialog.actions.spec.js
Images are in the /img sub-folder of the component, in folder. See React images
/button
|-- /img
| |-- icon-24x24.png
|
|-- button.component.jsx
|-- button.component.scss
NEVER EVER rename a file, by just changing capitalization. Seriously, NEVER !
$ # BAD - NEVER DO THIS
$ mv my-Source-Code-File.js my-source-code-file.js
If you desperately need to do it, you have to do it in 3 steps:
# STEP 1 - rename file by adding postfix
$ mv my-Source-Code-File.js my-source-code-file-ex.js
# STEP 2 - wait until change spreads into all open branches - this may take several weeks
# STEP 3 - rename file by removing postfix
$ mv my-source-code-file-ex.js my-source-code-file.js
To help git track changed files, never rename a file and change its content in one commit.
# BAD
$ mv my-file.js my-changed-name.js
# change content of my-changed-name.js file
$ git commit
# GOOD
$ mv my-file.js my-changed-name.js
$ git commit
# change content of my-changed-name.js file
$ git commit
/.storybook
/electron # only Electron specific files
/web # Web/browser specific code
/test # Test/nodejs specific code
/common
|-- /app # entry point to the application
| |-- action-types.js
| |-- app.actions.js
| |-- app.component.jsx
| |-- app.reducers.js
| |-- index.js
| |-- start-app.jsx
| |-- store-configuration.js
| |-- /middleware
| |-- /oauth
| |-- /authorization
| |-- /fetch
| |-- /global-error-handler
| |-- ...
|-- /i18n
| |-- en.json
| |-- de.json
| |-- sk.json
| |-- ru.json
|
|-- /shared
|-- /assets
| |-- innovatrics-ai.scss
|
|-- /components
| |-- /drop-down
| | |-- /img
| | | |-- icon-24x24.png
| | |
| | |-- drop-down.component.jsx
| | |-- drop-down.component.scss
| |-- /button
| | |-- button.component.jsx
| | |-- button.component.scss
| |-- /calendar
| |-- /chart
| |-- /context-menu
| |-- /collapsible
| |-- /modal-box
| |-- /switch-button
| |-- /toggle
| |-- ...
|-- /helpers
|-- /lib
|-- /codemirror
|-- /some-third-party-library
When using typescript, use a tool like GraphQL Code Generator to automatically generate typescript type definitions for your graphql queries.
When writing GraphQL query that includes Relay connection type, make sure to include @connection directive with key set to name of the connection (see example).
Connection results are saved in cache with its name and input arguments as key (watchlistItemConnection(first: 10, after: "abcdefgh")) - this means different pages are saved under diferent keys (before/after arguments are diferent each page). key in @connection directive makes sure results are saved and normalised under key, ingoring connection arguments. This is important for adding/removing data from cache after successful mutation, as we wouldn't be able to do it otherwise.
Example:
query watchlistQuery($id: ID!, $first: Int!) {
...
watchlistItemConnection(first: $first) @connection(key: "watchlistItemConnection") {
edges {
node {...}
}
}
}
Mutations that update something, should always return every field that can go into its input parameter. Apollo can update cache automatically through the whole application.
Example:
input WatchlistItemUpdateInput {
id: ID!
displayName: String
fullName: String
note: String
externalId: String
}
mutation updateWatchlistItem {
updateWatchlistItem($input: WatchlistItemUpdateInput!) {
watchlistItem {
id
displayName
fullName
note
externalId
}
}
}
Delete data from cache is a bit tricky, here is an example (using watchlistItemConnection):
// we dont't use pagination arguments in queries reading from apollo cache,
// as we used `@connection` directive in the original (server) query/queries
const CACHE_QUERY = gql`
...
watchlistItemConnection @connection(key: "watchlistItemConnection") {
edges {
node {...}
}
}
`;
mutation({
variables: { id: watchlistItemId },
update: (store: DataProxy) => {
const cache = store.readQuery({
query: CACHE_QUERY,
});
cache.watchlistItemConnection.edges = cache.watchlistItemConnection.edges.filter(edge => edge.node.id !== watchlistItemId);
store.writeQuery({
query: CACHE_QUERY,
data: cache,
});
}
})'