Accelerated News

This project was bootstrapped with React Accelerate. It demonstrates how one could build upon the foundation provided by React Accelerate. Specifically, this is an example of a simple News site with some content that is available publicly, while other content that is only available to authenticated users.

React Accelerate Features

1. TypeScript based - for type safety
2. Opinionated folder structure
3. Foundational libraries
   • React Router
4. Essential tools
   • Storybook to develop UI components in isolation
   • React Testing Library for unit testing
   • Cypress for end-to-end testing
   • Husky to improve the quality of commits
   • Mock Service Worker to mock HTTP requests
   • Prettier to format code consistently
5. Some useful starter components:
   • ErrorBoundary: A component to catch JavaScript errors anywhere in its child component tree and display a fallback UI.
   • Loading: A placeholder loading component
   • EnvProvider: Provides a mechanism for loading environment variables dynamically by placing an environment file (env.js) in the /public folder. This allows a single build to be used across multiple environments such as develop, qa, uat & prod.
   • Home: A simple page showing end-to-end flow from client to server. It makes an HTTP request to the server, which is intercepted by Mock Service Worker (in development mode) and displays a list of movies. The unit test for this page does not have to do any jest level mocking, demonstrating the power of MSW.
   • NotFound: A placeholder NotFound page
   • Sample Storybook Stories: Showing best practices in Storybook
   • Unit Testing: Utility functions to make testing easier. Also, some sample tests to show best practices.
   • End-to-End Testing: Sample Cypress tests to show best practices.

Implementation decisions made in this example

1. For this example, we have chosen to use pure CSS and CSS Variables to implement a simple design system. Obviously you can use any styling framework and component library in your own apps.
2. We have used BEM to properly namespace our styles. Of course, this is not needed if you use more modern techniques like CSS Modules or CSS-in-JS. However, it is always good to know the classic CSS techniques.
3. We have enhanced the starter components provided by React Accelerate and provided a few more. See inside the /src/components folder. You can get a better feel for these components in the project's Storybook.
4. We added a Style Guide section to our Storybook to show how documentation can be added using the Markdown syntax. For more information see the Storybook documentation.
5. We are using REST for communicating with the server. Specifically we are using an axios based HTTP client. We use an axios interceptor to simplify calling the server APIs. Of course, we are still leveraging Mock Service Worker (MSW) for local development.
6. We are using React Query to manage server state. You can find introductory videos on React Query here.
7. We have added token-based authentication to the application.
   • Users can sign up by supplying some basic information.
   • Once signed up, they can sign in using their credentials. If the credentials match, the server returns a unique access token to the front-end.
   • The front-end saves the access token in localStorage and returns it to the server in every HTTP request. The server uses this token to identify the user making the request.
   • When the user signs out, the access token is deleted from localStorage.
8. Authenticated users can add, update or delete news headlines on the Manage Headlines page. Access to this page is granted only to authenticated users. This is implemented using a PrivateRoute component, which extends react router's Route component.
9. Manage Headlines page demonstrates the use of the Master-Detail pattern to add or edit headlines.

Getting Started

Make sure your development machine is set up for building React apps. See the recommended setup procedure here.

Then execute the commands in one of the sections below depending on your preference of npm or yarn:

Building with npm

# note: "--legacy-peer-deps" option is required for npm version > v7
# see details here: https://github.com/storybookjs/storybook/issues/12983
npm install --legacy-peer-deps

# Execute the following commands to run the app:
npm start

Now point your browser to http://localhost:3000/.

Building with yarn

yarn

# Execute the following commands to run the app:
yarn start

Now point your browser to http://localhost:3000/.

Running Storybook

Storybook is a powerful tool for developing UI components in isolation, independent of the final app they will be deployed in. This approach has the following benefits:

1. Develop components without needing to build entire screens, fuss with data or business logic
2. Render components in key states that are tricky to reproduce in an app
3. Document components with examples and properties

React Accelerate comes ready with Storybook. Execute the following command to run Storybook.

npm run storybook

Running Unit Tests

React Accelerate comes ready with Jest and React Testing Library to run unit tests. Execute one of the following command to run unit tests.

npm run test # interactive mode
npm run test:coverage # non-interactive mode with coverage information

Note that unit tests are automatically executed when you commit code to your local repo. This ensures that you are not committing broken code.

Running End-to-End Tests

React Accelerate comes ready with Cypress to run end-to-end tests. Execute Cypress using the following commands:

npm start # starts a local server hosting your react app

# run cypress in a different shell
npm run cypress:open

Code Formatting

React Accelerate uses Prettier to consistently and easily format code. Prettier is an opinionated code formatter that provides the following benefits:

1. Code is formatted automatically without any fuss
2. There is no need to discuss style in code review
3. Saves you time and energy

Prettier is automatically executed when you commit code to your local repo. You can also execute it manually using the following command:

npm run format

Learn More

• React Learning Resources