This is a step-by-step guide to customize CRA for Atolye15 projects. You can review CRA Starter project to see how your application looks like when all steps followed.
You will get an application which has;
- TypeScript
- Sass
- Linting
- Formatting
- Testing
- CI/CD
- Storybook
- Step 1: Creating a new app
- Step 2: Removing CRA example files
- Step 3: Make TypeScript more strict
- Step 4: Installing Prettier
- Step 5: Installing ESLint
- Step 6: Enabling Sass
- Step 7: Installing stylelint
- Step 8: Setting up our test environment
- Step 9: Enabling hot reloading
- Step 10: Organizing Folder Structure
- Step 11: Adding Storybook
- Step 12: Adding React Router
- Step 13: Enabling code-splitting
- Step 14: Adding CircleCI config
- Step 15: Auto-deploy to Surge.sh
- Step 16: Github Settings
- Step 17 Final Touches
- Step 18: Starting to Development π
First of all, we need to initialize our codebase via CRA command.
npx create-react-app cra-starter --template typescript
cd cra-starter
yarn start
In order to create our stack, we need to remove unnecessary CRA files.
We want to keep type safety as strict as possibble. In order to do that, we update tsconfig.json
with the settings below.
"noImplicitAny": true,
"noImplicitReturns": true,
We want to format our code automatically. So, we need to install Prettier.
yarn add prettier --dev
.prettierrc
{
"printWidth": 100,
"singleQuote": true,
"trailingComma": "all"
}
.prettierignore
build
Also, we want to enable format on save on VSCode.
.vscode/settings.json
{
"editor.formatOnSave": true,
}
Finally, we update package.json
with related format scripts.
"format:ts": "prettier --write 'src/**/*.{ts,tsx}'",
"format": "yarn run format:ts",
"format:check": "prettier -c 'src/**/*.{ts,tsx}'"
We want to have consistency in our codebase and also want to catch mistakes. So, we need to install ESLint.
yarn add eslint @atolye15/eslint-config --dev
.eslintrc
{
"extends": [
"@atolye15/eslint-config"
]
}
.eslintignore
public
build
react-app-env.d.ts
.vscode/settings.json
{
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
}
We need to update package.json
for ESLint scripts.
"lint": "yarn run lint:ts",
"lint:ts": "tsc && yarn lint:eslint",
"lint:eslint": "eslint 'src/**/*.{ts,tsx}'",
"format:ts": "prettier --write 'src/**/*.{ts,tsx}' && yarn lint:eslint --fix",
CRA comes with Sass support out of the box. In order to enable it, we only add node-sass
to our project.
yarn add node-sass --dev
We also want a linter for our sass files. We need to install stylelint
.
yarn add stylelint stylelint-config-prettier stylelint-prettier @atolye15/stylelint-config --dev
.stylelintrc
{
"extends": ["@atolye15/stylelint-config", "stylelint-prettier/recommended"]
}
Finally, we need to update package.json
and .vscode/settings.json
package.json
"lint:css": "stylelint --syntax scss \"src/**/*.scss\"",
"lint": "yarn run lint:ts && yarn run lint:css",
"format:css": "stylelint --fix --syntax scss \"src/**/*.scss\"",
"format": "yarn run format:ts && yarn run format:css"
We'll use jest
with enzyme
.
yarn add enzyme enzyme-adapter-react-16 react-test-renderer --dev
yarn add @types/enzyme @types/enzyme-adapter-react-16 --dev
Also we need to install enzyme-to-json
for simpler snapshosts.
yarn add enzyme-to-json --dev
We update our package.json
for jest configuration.
"scripts": {
"coverage": "yarn run test --coverage"
},
"jest": {
"snapshotSerializers": [
"enzyme-to-json/serializer"
],
"collectCoverageFrom": [
"src/**/*.{ts,tsx}",
"!src/index.tsx",
"!src/setupTests.ts",
"!src/components/**/index.{ts,tsx}",
"!src/components/**/*.stories.{ts,tsx}"
],
"coverageThreshold": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
And finally, we need to add the coverage
to .gitignore
and .prettierignore
.
.eslintignore
# ...
coverage
.prettierignore
# ...
coverage
Before the testing, we need to add our setup file to initialize enzyme.
src/setupTests.ts
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
configure({ adapter: new Adapter() });
With this config, we are able to run tests with snapshots and create coverage. Let's add a simple test to verify our setup.
src/App.test.tsx
import React from 'react';
import { shallow } from 'enzyme';
import App from './App';
it('runs correctly', () => {
const wrapper = shallow(<App />);
expect(wrapper).toMatchSnapshot();
});
Also, verify coverage report with yarn coverage
.
We want to take advantage of hot reloading and don't want to lose React's current state. In order to do that we can use react hot loader. Since, we use CRA and don't want to eject it, we need to use customize-cra
package.
yarn add react-app-rewired customize-cra @hot-loader/react-dom --dev
After the installation we need to update package.json
scripts to use react-app-rewired
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-app-rewired eject"
Now, we can install react-hot-loader
.
yarn add react-hot-loader
Also we need to update hot reloader config.
src/index.tsx
import { setConfig } from 'react-hot-loader';
setConfig({
ignoreSFC: true,
pureRender: true,
});
In order to update babel config for hot loader, we need to create a config-overrides.js
file on the root.
// eslint-disable-next-line @typescript-eslint/no-var-requires
const { override, addBabelPlugin, addWebpackAlias } = require('customize-cra');
module.exports = override(
addBabelPlugin('react-hot-loader/babel'),
addWebpackAlias({
'react-dom': '@hot-loader/react-dom',
}),
);
Lastly, we need to use hot HOC.
src/App.tsx
import React from 'react';
import { hot } from 'react-hot-loader/root';
export default hot(App);
Our folder structure should look like this;
src/
βββ App.test.tsx
βββ App.tsx
βββ __snapshots__
β βββ App.test.tsx.snap
βββ components
β βββ Button
β βββ Button.scss
β βββ Button.stories.tsx
β βββ Button.test.tsx
β βββ Button.tsx
β βββ __snapshots__
β β βββ Button.test.tsx.snap
β βββ index.ts
βββ containers
β βββ Like
β βββ Like.tsx
β βββ index.ts
βββ fonts
βββ img
βββ index.tsx
βββ react-app-env.d.ts
βββ routes
β βββ Feed
β β βββ Feed.scss
β β βββ Feed.test.tsx
β β βββ Feed.tsx
β β βββ index.ts
β β βββ tabs
β β βββ Discover
β β β βββ Discover.scss
β β β βββ Discover.test.tsx
β β β βββ Discover.tsx
β β β βββ index.ts
β β βββ MostLiked
β β βββ MostLiked.test.tsx
β β βββ MostLiked.tsx
β β βββ index.ts
β βββ Home
β β βββ Home.scss
β β βββ Home.test.tsx
β β βββ Home.tsx
β β βββ index.ts
β βββ index.ts
βββ setupTests.ts
βββ styles
β βββ index.scss
βββ utils
βββ location.test.ts
βββ location.ts
We need to initialize the Storybook on our project.
npx -p @storybook/cli sb init --type react
We also need to add info
addon and react-docgen-typescript-loader
package to show component props on our stories (Optional but recommended).
yarn add @storybook/addon-info react-docgen-typescript-loader --dev
We have to use the custom Webpack config in full control mode, extending default configs by creating a webpack.config.js
file in our Storybook configuration directory (by default, itβs .storybook
):
.storybook/webpack.config.js
module.exports = ({ config, mode }) => {
config.module.rules.push({
test: /\.(ts|tsx)$/,
use: [
{
loader: require.resolve('babel-loader'),
options: {
presets: [require.resolve('babel-preset-react-app')],
},
},
require.resolve('react-docgen-typescript-loader'),
],
});
config.resolve.extensions.push('.ts', '.tsx');
return config;
};
Since we use typescript
, we can change the file extensions (addons
and config
) to .ts
in .storybook
folder. Then we need to update storybook config to register info addon, and stories directory.
.storybook/config.ts
import { configure, addDecorator } from '@storybook/react';
import { withInfo } from '@storybook/addon-info';
// automatically import all files ending in *.stories.tsx
const req = require.context('../src/components', true, /.stories.tsx$/);
function loadStories() {
addDecorator(withInfo);
req.keys().forEach(req);
}
configure(loadStories, module);
We will place the stories inside component folders, you can delete the
stories
folder which is created by storybook initialization process.
Let's create a story for our Button component.
src/components/Button/Button.stories.tsx
import React from 'react';
import { storiesOf } from '@storybook/react';
import Button from './Button';
storiesOf('Button', module)
.add('Primary', () => <Button primary>Primary Button</Button>)
.add('Secondary', () => <Button secondary>Secondary Button</Button>);
Run storybook
yarn storybook
As usual, we want to use react-router
for routing.
yarn add react-router-dom
yarn add @types/react-router-dom --dev
Then, we need to encapsulate our root component with BrowserRouter
.
// src/index.tsx
import React, { FunctionComponent } from 'react';
import ReactDOM from 'react-dom';
import { setConfig } from 'react-hot-loader';
import { BrowserRouter } from 'react-router-dom';
import App from './App';
setConfig({
ignoreSFC: true,
pureRender: true,
});
const Root: FunctionComponent = () => (
<BrowserRouter>
<App />
</BrowserRouter>
);
ReactDOM.render(<Root />, document.getElementById('root'));
// src/routes/Routes.tsx
import React, { FunctionComponent } from 'react';
import { Switch, Route } from 'react-router-dom';
import Home from './Home';
import Feed from './Feed';
const Routes: FunctionComponent = () => (
<Switch>
<Route path="/" exact component={Home} />
<Route path="/feed" exact component={Feed} />
</Switch>
);
export default Routes;
// src/App.tsx
import React, { FunctionComponent, Fragment } from 'react';
import { hot } from 'react-hot-loader';
import Routes from './routes';
const App: FunctionComponent = () => (
<Fragment>
<header>Header</header>
<Routes />
<footer>Footer</footer>
</Fragment>
);
export default hot(module)(App);
We want to make route based code-splitting in order to prevent a huge bundled asset. When we done with this, only relevant assets will be loaded by our application. Let's install react-loadable
.
yarn add react-loadable
yarn add @types/react-loadable --dev
Now, let's convert our routes to dynamically loaded.
// src/routes/Home/index.ts
import Loadable from 'react-loadable';
import Loading from '../../components/Loading';
const LoadableHome = Loadable({
loader: () => import('./Home'),
loading: Loading,
});
export default LoadableHome;
// src/routes/Feed/index.ts
import Loadable from 'react-loadable';
import Loading from '../../components/Loading';
const LoadableFeed = Loadable({
loader: () => import('./Feed'),
loading: Loading,
});
export default LoadableFeed;
We can create a CircleCI pipeline in order to CI / CD.
# .circleci/config.yml
version: 2
jobs:
build_dependencies:
docker:
- image: circleci/node:10
working_directory: ~/repo
steps:
- checkout
- attach_workspace:
at: ~/repo
- restore_cache:
keys:
- dependencies-{{ checksum "package.json" }}
- dependencies-
- run:
name: Install
command: yarn install
- save_cache:
paths:
- ~/repo/node_modules
key: dependencies-{{ checksum "package.json" }}
- persist_to_workspace:
root: .
paths: node_modules
test_app:
docker:
- image: circleci/node:10
working_directory: ~/repo
steps:
- checkout
- attach_workspace:
at: ~/repo
- run:
name: Lint
command: yarn lint
- run:
name: Format
command: yarn format:check
- run:
name: Test
command: yarn test
- run:
name: Coverage
command: yarn coverage
workflows:
version: 2
build_app:
jobs:
- build_dependencies
- test_app:
requires:
- build_dependencies
After that we need to enable CircleCI for our repository.
First of all, we need to retrieve our Surge.sh token.
surge token
After copying the value, we need to add it as a dev dependency.
yarn add surge --dev
We need to add surge token to CircleCI as an environment variable for our project. Please update project name in the url;
https://circleci.com/gh/atolye15/{PROJET_NAME}/edit#env-vars
On the page, we'll add SURGE_LOGIN
and SURGE_TOKEN
envs with the email and token we got before. We're almost ready. Let's update our CircleCI config.
# .circleci/config.yml
version: 2
jobs:
build_dependencies:
docker:
- image: circleci/node:10
working_directory: ~/repo
steps:
- checkout
- attach_workspace:
at: ~/repo
- restore_cache:
keys:
- dependencies-{{ checksum "package.json" }}
- dependencies-
- run:
name: Install
command: yarn install
- save_cache:
paths:
- ~/repo/node_modules
key: dependencies-{{ checksum "package.json" }}
- persist_to_workspace:
root: .
paths: node_modules
test_app:
docker:
- image: circleci/node:10
working_directory: ~/repo
steps:
- checkout
- attach_workspace:
at: ~/repo
- run:
name: Lint
command: yarn lint
- run:
name: Format
command: yarn format:check
- run:
name: Test
command: yarn test
- run:
name: Coverage
command: yarn coverage
deploy_app:
docker:
- image: circleci/node:10
working_directory: ~/repo
steps:
- checkout
- attach_workspace:
at: ~/repo
- run:
name: Deploy
command: yarn deploy
workflows:
version: 2
build_app:
jobs:
- build_dependencies
- test_app:
requires:
- build_dependencies
- deploy_app:
requires:
- test_app
filters:
branches:
only: master
Let's add deploy script to our package.json
.
"deploy": "sh deploy.sh"
Finally, we need to create a deploy.sh
file.
echo 'Building application...'
yarn build
echo 'Copying index.html as 404.html'
cp build/index.html build/404.html
echo 'Deploying...'
node_modules/.bin/surge --project ./build --domain cra-starter.surge.sh
echo 'Deployed π'
NOTE: Of course, you can replace Surge.sh with anything else. For this, you only need to update Surge.sh parts.
We want to protect our develop
and master
branches. Also, we want to make sure our test passes and at lest one person reviewed the PR. In order to do that, we need to update branch protection rules like this in GitHub;
We are ready to develop our application. Just a final step, we need to update our README.md
to explain what we add a script so far.
This project was set up with following [CRA Recipe](https://github.com/atolye15/cra-recipe).
## Available Scripts
In the project directory, you can run:
### `yarn start`
Runs the app in the development mode.<br>
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
The page will hot reload if you make edits.<br>
You will also see any lint errors in the console.
### `yarn test`
Launches the test runner in the interactive watch mode.<br>
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
### `yarn coverage`
Launches coverage reporter. You can view the details from `coverage` folder.
### `yarn lint`
Runs ESLint and StyleLint. If any lint errors found, then it exits with code 1.
### `yarn format`
Formats TypeScript and Sass files.
### `yarn format:check`
Checkes if any formatting error has been made.
### `yarn storybook`
Launches Storybook application.
### `yarn build`
Builds the app for production to the `build` folder.<br>
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.<br>
Your app is ready to be deployed!
### `yarn deploy`
Deploys app to given platform according to instuctions in `deploy.sh`
## Learn More
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
To learn React, check out the [React documentation](https://reactjs.org/).
Everything is done! You can start to develop your next awesome React application now on π
- crna-recipe - React Native App Creation Recipe