test-throw-away-app v0.0.17
Notes
package.json
"name": "@Monitoring/Monitoring.monitoring-summary-app", "version": "0.0.0-setByBuild",
"name": "test-throw-away-app", "version": "0.0.11",
Folder Structure
After creation, your project should look like this:
my-component/
README.md
node_modules/
package.json
src/
main.ts
SampleComponent.tsx
SampleComponent.test.tsx
tsconfig.json
tsconfig.test.json
tslint.json
For the project to build, these files must exist with exact filenames:
src/main.ts
is the JavaScript entry point, where you export your component in order to be consumed.
You can delete or rename the other files.
You need to put any TS, TSX and CSS files inside src
, otherwise the compiler won’t see them.
Available Scripts
In the project directory, you can run:
npm test-watch
Launches the test runner in the interactive watch mode. See the section about running tests for more information.
npm run build
Builds the app for production to the dist
folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
Your component is ready to be deployed!
See the section about deployment for more information.
yarn storybook
Runs Storybook, which is an interactive UI development enviornment that allows you to visualize your component and edit the properties of your component in real time.
Supported Browsers
By default, the generated project uses the latest version of React.
You can refer to the React documentation for more information about supported browsers.
Supported Language Features and Polyfills
This project supports a superset of the latest JavaScript standard. In addition to ES6 syntax features, it also supports:
- Exponentiation Operator (ES2016).
- Async/await (ES2017).
- Object Rest/Spread Properties (stage 3 proposal).
- Dynamic import() (stage 3 proposal)
- Class Fields and Static Properties (stage 2 proposal).
- JSX and Flow syntax.
Learn more about different proposal stages.
While we recommend to use experimental proposals with some caution, Facebook heavily uses these features in the product code, so we intend to provide codemods if any of these proposals change in the future.
Note that the project only includes a few ES6 polyfills:
Object.assign()
viaobject-assign
.Promise
viapromise
.fetch()
viawhatwg-fetch
.
If you use any other ES6+ features that need runtime support (such as Array.from()
or Symbol
), make sure you are including the appropriate polyfills manually, or that the browsers you are targeting already support them.
Debugging in the Editor
This feature is currently only supported by Visual Studio Code and WebStorm.
Visual Studio Code and WebStorm support debugging out of the box with Create React App. This enables you as a developer to write and debug your React code without leaving the editor, and most importantly it enables you to have a continuous development workflow, where context switching is minimal, as you don’t have to switch between tools.
Formatting Code Automatically
Prettier is an opinionated code formatter with support for JavaScript, CSS and JSON. With Prettier you can format the code you write automatically to ensure a code style within your project. See the Prettier's GitHub page for more information, and look at this page to see it in action.
To format our code whenever we make a commit in git, we need to install the following dependencies:
npm install --save husky lint-staged prettier
Alternatively you may use yarn
:
yarn add husky lint-staged prettier
husky
makes it easy to use githooks as if they are npm scripts.lint-staged
allows us to run scripts on staged files in git. See this blog post about lint-staged to learn more about it.prettier
is the JavaScript formatter we will run before commits.
Now we can make sure every file is formatted correctly by adding a few lines to the package.json
in the project root.
Add the following line to scripts
section:
"scripts": {
+ "precommit": "lint-staged",
"start": "react-scripts start",
"build": "react-scripts build",
Next we add a 'lint-staged' field to the package.json
, for example:
"dependencies": {
// ...
},
+ "lint-staged": {
+ "src/**/*.{js,jsx,json,css}": [
+ "prettier --single-quote --write",
+ "git add"
+ ]
+ },
"scripts": {
Now, whenever you make a commit, Prettier will format the changed files automatically. You can also run ./node_modules/.bin/prettier --single-quote --write "src/**/*.{js,jsx,json,css}"
to format your entire project for the first time.
Next you might want to integrate Prettier in your favorite editor. Read the section on Editor Integration on the Prettier GitHub page.
Installing a Dependency
The generated project includes React and ReactDOM as dependencies. It also includes a set of scripts used by Create React App as a development dependency. You may install other dependencies (for example, React Router) with npm
:
npm install --save react-router
Alternatively you may use yarn
:
yarn add react-router
This works for any library, not just react-router
.
Importing a Component
This project setup supports ES6 modules
While you can still use require()
and module.exports
, we encourage you to use import
and export
instead.
For example:
Button.js
import React, { Component } from 'react';
class Button extends Component {
render() {
// ...
}
}
export default Button; // Don’t forget to use export default!
DangerButton.js
import React, { Component } from 'react';
import Button from './Button'; // Import a component from another file
class DangerButton extends Component {
render() {
return <Button color="red" />;
}
}
export default DangerButton;
Be aware of the difference between default and named exports. It is a common source of mistakes.
We suggest that you stick to using default imports and exports when a module only exports a single thing (for example, a component). That’s what you get when you use export default Button
and import Button from './Button'
.
Named exports are useful for utility modules that export several functions. A module may have at most one default export and as many named exports as you like.
Learn more about ES6 modules:
Consuming the Component in another app:
- Add it as a dependency to your app's package.json:
npm install --save your-component
- Import it in any page of your app as a module:
import { YourComponent } from 'your-component'
- Be mindful that the name
YourComponent
must match the name of the export inmain.ts
export { default as YourComponent } from './YourComponent'
Serving the Component without publishing
- Import the component in demo/index.tsx as a module:
import { YourComponent } from 'your-component'
Add the component as a
HTML tag
with attributes if needed in therender()
function.Start the server using:
yarn start
Adding Images, Fonts, and Files
With Webpack, using static assets like images and fonts works similarly to CSS.
You can import
a file right in a TypeScript module. This tells Webpack to include that file in the bundle. Unlike CSS imports, importing a file gives you a string value. This value is the final path you can reference in your code, e.g. as the src
attribute of an image or the href
of a link to a PDF.
To reduce the number of requests to the server, importing images that are less than 10,000 bytes returns a data URI instead of a path. This applies to the following file extensions: bmp, gif, jpg, jpeg, and png. SVG files are excluded due to #1153.
Before getting started, you must define each type of asset as a valid module format. Otherwise, the TypeScript compiler will generate an error like this:
Cannot find module './logo.png'.
To import asset files in TypeScript, create a new type definition file in your project, and name it something like assets.d.ts
. Then, add a line for each type of asset that you need to import:
declare module '*.gif';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.png';
declare module '*.svg';
(you'll have to restart the compiler in order the changes to take place)
In this case, we've added several image file extensions as valid module formats.
Now that the compiler is configured, here is an example of importing an image file:
import React from 'react';
import logo from './logo.svg'; // Tell Webpack this JS file uses this image
console.log(logo); // /logo.84287d09.png
function Header() {
// Import result is the URL of your image
return <img src={logo} alt="Logo" />;
}
export default Header;
This ensures that when the project is built, Webpack will correctly move the images into the build folder, and provide us with correct paths.
This works in CSS too:
.Logo {
background-image: url(./logo.png);
}
Webpack finds all relative module references in CSS (they start with ./
) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets.
Please be advised that this is also a custom feature of Webpack.
It is not required for React but many people enjoy it (and React Native uses a similar mechanism for images).
Running Tests
This template uses Jest as its test runner.
Jest is a Node-based runner. This means that the tests always run in a Node environment and not in a real browser. This lets us enable fast iteration speed and prevent flakiness.
While Jest provides browser globals such as window
thanks to jsdom, they are only approximations of the real browser behavior. Jest is intended to be used for unit tests of your logic and your components rather than the DOM quirks.
We recommend that you use a separate tool for browser end-to-end tests if you need them. They are beyond the scope of Create React App.
Filename Conventions
Jest will look for test files with any of the following popular naming conventions:
- Files with
.test.tsx
suffix.
Command Line Interface
When you run yarn test-watch
, Jest will launch in the watch mode. Every time you save a file, it will re-run the tests.
The watcher includes an interactive command-line interface with the ability to run all tests, or focus on a search pattern. It is designed this way so that you can keep it open and enjoy fast re-runs. You can learn the commands from the “Watch Usage” note that the watcher prints after every run:
Getting Started with Storybook
Storybook is a development environment for React UI components. It allows you to browse a component library, view the different states of each component, and interactively develop and test components.
First, install the following npm package globally:
npm install -g @storybook/cli
Then, run the following command inside your app’s directory:
getstorybook
After that, follow the instructions on the screen.
Storybook Integration Tests
To run integration (Storybook snapshot) tests in a Docker container, run
yarn test:integration-container
To run integration tests on your local machine, run
yarn test:integration
Running integration tests on your local machine will most likely result in image mismatch errors due to the potential differences between Chrome's image rendering in the container and on your local machine.
The images generated from this local test should not be checked in, but only used as a sanity check (see src\widgets\__image_snapshots__\__diff_output__
). Note that the puppeteer package specified in package.json is used only for running integration tests locally. The actual version of puppeteer used in CI (container) integration tests is specified in /src/test/Dockerfile
.
To add a test case,
- Add the story in
src\app\stories\index.js
- Add a matching test in
src\app\src\widgets\FinancialWidget.Snapshot.Integration.test.js
, where the URL can be obtained from Storybook - Run
yarn update-image-snapshots
. This will update image snapshots in the local drive which can then be checked in.
Advanced:
It is possible to modify files in the container generated by yarn update-image-snapshots
and use it for further image updates.
First start the container and start a shell in it using docker start [container name] && docker exec -it [container name] sh
.
Then modify files and run commands as desired, e.g. yarn container:integration
or yarn container:integration-update
.
To copy images out from the container again, run the following in a local terminal:
docker cp [container name]:/app/src/widgets/__image_snapshots__/. ./app/src/widgets/__image_snapshots__
Learn more about React Storybook and image snapshot integration testing: