@sumup/create-sumup-react-app

⚛️ create-sumup-react-app ⚛️

The easiest way to get started writing a React app with SumUp's standard frontend toolchain.

Table of Contents

• 💻 Prerequisites
• ✨ Setting up a new SumUp React project
• 🛠 Development workflow
  • Firing up the tools
  • Adding a new component
  • Linting your code
  • Writing tests
• 📖 Useful resources
• 💁‍♀ Tips
  • Setting up Foundry's ESLint in your editor
    • Visual Studio Code
• ⚠️ Troubleshooting
  • Debug mode
  • Engine node is incompatible
  • Error watching file for changes
• Code of conduct (CoC)
  • Maintainers
• About SumUp

💻 Prerequisites

• You should have Node.js installed at a version equal or above v9.10.0. If you cannot do that, see the Troubleshooting section for ways around this requirement.
• At the moment this project reqires yarn to be installed on your system. Yarn is a package manager for JavaScript. You can read how to install the Yarn CLI in their documentation.
• You will need npx installed. You can run yarn global add npx or npm install -g npx to make that happen.

✨ Setting up a new SumUp React project

1. Open your terminal.
2. Navigate to the directory you would like to place your project in.
3. Run yarn create @sumup/sumup-react-app my-app, where my-app is the name of your project.

This will create the folder my-app and initialize a new project inside. The project will be based on create-react-app and will use the SumUp's Circuit UI component library and Foundry toolkit.

🛠 Development workflow

Firing up the tools

Run yarn start to start the development build. The app should automatically open in your browser. Changes you make to src/App.js should be visible on the page almost immediately.

To create a production build of your app, run yarn build. react-scripts will create an optimized production build of your application inside the build folder of your project. It will also provide you with additional details on what to do with them.

Adding a new component

We try making adding new components as easy as possible. Run yarn create-component YourComponentName to launch the plop CLI exposed and configured by Foundry.

Linting your code

A linter is a tool that checks your code for:

• problems that will cause it to break when run, or
• code style that violates a given set of rules the project is following.

Linting serves as a first line of defence against evil bugs on production.​ Your project will be set up to use a version of the popular ESLint linter for JavaScript provided by Foundry. You can lint your code and apply automatic fixes by running yarn lint. Usually, your editor is able to integrate with ESLint. Check your options and refer to the Tips section for details on how to make this work with Foundry.

Writing tests

Writing tests is great. Tests are the second line of defence against bugs ending up on production. By covering your application in unit and integration tests, you can be sure you did not break anything when, for example, shipping refactored code to production. Your new React project comes with testing built in. By running yarn test you will start the test runner, Jest. As you add tests or make changes to your code, Jest will re-run tests and show you the results. The app will come with react-testing-library set up for writing UI tests for your React components. Check out src/App.spec.js for examples.

📖 Useful resources

• The docs for create-react-app contain a lot of solutions for common problems when writing a React application.
• Foundry docs.
• Circuit UI docs and storybook.
• The README forreact-testing-library.

💁‍♀ Tips

Setting up Foundry's ESLint in your editor

The great strength of using a toolkit like Foundry is that you as a user do not have to care about developer dependencies like ESLint. Foundry manages and runs them for you via its run command. This, however, becomes a bit tricky when you want your text editor or IDE to run ESLint on your code as you edit it. To get this working, you need to tell your editor where to look for ESLint dependencies.

Your mileage may vary depending on your text editor, but we try to keep a list of instructions here.

Visual Studio Code

The ESLint extension for VSCode has a nodePath setting. It allows you to add additional paths where the plugin should look when resolving dependencies. By setting it to the default path of Foundry in a project's node_modules, you will make VSCode work with Foundry's version of ESLint. Put the following line in your settings.json.

"eslint.nodePath": "node_modules/@sumup/foundry/node_modules",

Don't worry, this won't break ESLint for other projects. It just gives VSCode another relative path where it can look for ESLint.

⚠️ Troubleshooting

Debug mode

create-sumup-react-app has a debug mode. To output verbose logging to your console, add the --debug flag when creating your app. For example:

yarn create @sumup/sumup-react-app my-debugging-app --debug

Engine node is incompatible

error eslint@5.0.1: The engine "node" is incompatible with this module. Expected version "^6.14.0 || ^8.10.0 || >=9.10.0".
error Found incompatible module

Use a version of node that is compatible with ESLint. If you cannot install it globally, you may try nvm, nodenv, or similar tools.

Error watching file for changes

2017-05-02 09:49 node[8980] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22)
2017-05-02 09:49 node[8980] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22)
2017-05-02 09:49 node[8980] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22)
events.js:163
      throw er; // Unhandled 'error' event
      ^

Error: Error watching file for changes: EMFILE
    at exports._errnoException (util.js:1050:11)
    at FSEvent.FSWatcher._handle.onchange (fs.js:1376:11)
error Command failed with exit code 1.

Make sure you have watchman installed. On macOS and Homebrew as your package manager, you can install it with the following line.

brew install watchman

Code of conduct (CoC)

We want to foster an inclusive and friendly community around our Open Source efforts. Like all SumUp Open Source projects, this project follows the Contributor Covenant Code of Conduct. Please, read it and follow it.

If you feel another member of the community violated our CoC or you are experiencing problems participating in our community because of another individual's behavior, please get in touch with our maintainers. We will enforce the CoC.

Maintainers

• Connor Bär
• Felix Jung

About SumUp

SumUp

It is our mission to make easy and fast card payments a reality across the entire world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Go, Java, Erlang, Elixir and more. Want to come work with us? Head to our careers page to find out more.