Cheers mate! 🍻
This document is survived by you! Please help us keep this a living document by updating and improving our documentation.
- Your-App-Name-Goes-Here
- Installation & Startup
- Standards & Best Practices
- Documentation
- Build Information
- Troubleshooting
This project was bootstrapped with React App Rewired which wraps Create React App to seamlessly and and override webpack configurations.
Solving problems with who is responsible for rendering the UI.
Provider pattern, HOC, renderProp
If you think you want to create an HOC. Implement it using a renderProp first. They are more flexible. Those who need the flexibility can use the render prop. Those who want something more simple, can use it as an HOC.
Article > state Reducer Pattern
- redux state like tree, using reducers to manage it's state. Just like redux. This pattern gives you complete control over the internal state of the component in a, albeit a bit complex, well-managed way.
sync state pattern (46:00) - for logic that needs to manage same state (keep in sync) two or more components This is controlled props
The documenation listed here is specific to the project starter. To view a more broad set of testing standards, view Test Standards and possibly other javascript testing information.
For react + redux apps and a fantastic article on "how to test react components" from freecodecamp you can use as a great introduction.
This project takes advantage of the following testing tools:
- Jest is used to test all JavaScript code. It includes test assertions, a powerful mocking library, and integration with istanbul for test coverage reporting.
- Enzyme is a JavaScript Testing utility for React that makes it easier to assert, manipulate, and traverse your React Components' output.
- Istanbul is a code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. This is integrated with Jest.
If our test setup and configuration interests you, or if there is ever a need to add to it, you can read up on "how" and "why" the testing framework is configured. Documentation for test setup and configuration is located within our test config directory.
Configuration for these metrics is maintained inside package.json. Jest allows you to maintain a separate configuation file, however because we bootstrap the app with create-react-app, the jest configuration must be maintained within the package.json as a top-level property. In order to override this we would need to extend the existing webpack configuration for testing with our own implementation.
Jest by default will run in a web environment using jsdom. Thought you might have noticed we include a specific --env=jsdom flag with our test scripts. This is another side effect from extending create-react-app which changes the default environemnt to node for improved performance. Not a big deal, but it's important to know why.
JSDoc has several forms of documenting the same thing. That's fine but it's easier when jumping into a project to have a bit of consistency. The following should clear up an ambiguity regarding preferences when using jsdoc.
Linking to external resources, ie https://www.google.com/ .
Prefer,
// provided a name -- prefer
[link text]{@link namepathOrURL}
// no name -- only when a name does not make a whole lot of sense (rare case)
{@link namepathOrURL}This approach is much quicker to read and understand what said string links to as opposed to parsing the url string to figure that out. URLs can be qutie log and ambiguous at times. Provided a name, first, is clear and tells the reader immediately what said link is all about.
Builds follow create-react-app which you can read more about there.
You can serve the build folder from a static server, one caveat, if you've set the homepage (we
do) in your package.json reference URLs won't resolve correctly. That is because they resolve
based on the PUBLIC_URL env variable; this is a node env.
In order to work around this you have two options
- remove the
homepageproperty, or per create-react-app, set it to. - set the
PUBLIC_URLon build.
Point 2 is easier imo but do what you want. Toss it on a static server of your choice
http-server and serve are both good choices if you don't have a preference.
If you only want something to work quickly, you can run these commands after build.
First, install http-server or serve globally.
# http-server
npm i -g http-server
# http-serve
npm i -g serverRun the build using setting the PUBLIC_URL or use the included npm script npm run build:static
# setting env vars is different for different OS
PUBLIC_URL=.Serve the build dir
# use -p to specify the port, ie `-p 5000` or use the default port
# http-server
http-server build -p 3000 --cors
# serve
serve build -p 3000http-server offers an easier CLI to reference but also requires you to specify disabling CORS for local access.
With earlier versions of npm, whenever you install a dependency the package.json will reformat to use a 2-space indentation.
This is a known issue with earlier versions of npm, specifically npm@4.*. Starting with npm@5.0.0 this is no longer an issue.
For reference, see:
If you are the latest release of jest with an earlier version of node, any version below 7.*, you will run into problems with tests, or units of code under test, that use the latest and greatest ES+ features.
Jest removed a dependency on babel-polyfill in early 2017 (no idea which version) which would previously,
as one might expect from the name, polyfill the latest ES standards. There are a couple of listed reasons
for removing this dependency which you can read more about in the resources section below.
As an example, if you use Object.entries or Object.values, your test will fail with TypeError because
methods won't exist (pssst, they exist in node v7+)
Several solutions exist:
- Update your node version to anything 7.* or greater
- Setup jest to polyfill the specific methods you need
- Import
babel-polyfill - Customize your
package.jsonor use a.babelrcwithbabel-polyfill - ...some other ways not listed.