Candidates

A little app enabling members to learn about candidates for an election

Getting set up in development

• Install yarn npm install --global yarn
• Duplicate .env.sample and rename it to .env
• Set the spreadsheet ids in .env
• Install dependencies & build data npm run bootstrap

Running the app in development

• Start the client npm run start
• Open the app open http://localhost:3000

Make a build to deploy

• Build the project npm run build
• Static build will be in /build

---

This project was bootstrapped with Create React App.

Below you will find some information on how to perform common tasks.
You can find the most recent version of this guide here.

Folder Structure

After creation, your project should look like this:

my-app/
  README.md
  node_modules/
  package.json
  public/
    index.html
    favicon.ico
  server/
  src/
    App.css
    App.js
    App.test.js
    index.css
    index.js
    logo.svg

For the project to build, these files must exist with exact filenames:

• public/index.html is the page template;
• src/index.js is the JavaScript entry point.

You can delete or rename the other files.

You may create subdirectories inside src. For faster rebuilds, only files inside src are processed by Webpack.
You need to put any JS and CSS files inside src, or Webpack won’t see them.

Only files inside public can be used from public/index.html.
Read instructions below for using assets from JavaScript and HTML.

You can, however, create more top-level directories.
They will not be included in the production build so you can use them for things like documentation.

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

npm test

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 build folder.
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.
Your app is ready to be deployed!

See the section about deployment for more information.

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).
• 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() via object-assign.
• Promise via promise.
• fetch() via whatwg-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.

Integrating with an API Backend

These tutorials will help you to integrate your app with an API backend running on another port, using fetch() to access it.

Node

Check out this tutorial. You can find the companion GitHub repository here.

Proxying API Requests in Development

Note: this feature is available with react-scripts@0.2.3 and higher.

People often serve the front-end React app from the same host and port as their backend implementation.
For example, a production setup might look like this after the app is deployed:

/             - static server returns index.html with React app
/todos        - static server returns index.html with React app
/api/todos    - server handles any /api/* requests using the backend implementation

Such setup is not required. However, if you do have a setup like this, it is convenient to write requests like fetch('/api/todos') without worrying about redirecting them to another host or port during development.

To tell the development server to proxy any unknown requests to your API server in development, add a proxy field to your package.json, for example:

  "proxy": "http://localhost:4000",

This way, when you fetch('/api/todos') in development, the development server will recognize that it’s not a static asset, and will proxy your request to http://localhost:4000/api/todos as a fallback. The development server will only attempt to send requests without a text/html accept header to the proxy.

Conveniently, this avoids CORS issues and error messages like this in development:

Fetch API cannot load http://localhost:4000/api/todos. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Keep in mind that proxy only has effect in development (with npm start), and it is up to you to ensure that URLs like /api/todos point to the right thing in production. You don’t have to use the /api prefix. Any unrecognized request without a text/html accept header will be redirected to the specified proxy.

The proxy option supports HTTP, HTTPS and WebSocket connections.
If the proxy option is not flexible enough for you, alternatively you can:

• Enable CORS on your server (here’s how to do it for Express).
• Use environment variables to inject the right server host and port into your app.

Using HTTPS in Development

Note: this feature is available with react-scripts@0.4.0 and higher.

You may require the dev server to serve pages over HTTPS. One particular case where this could be useful is when using the "proxy" feature to proxy requests to an API server when that API server is itself serving HTTPS.

To do this, set the HTTPS environment variable to true, then start the dev server as usual with npm start:

Pre-Rendering into Static HTML Files

If you’re hosting your build with a static hosting provider you can use react-snapshot to generate HTML pages for each route, or relative link, in your application. These pages will then seamlessly become active, or “hydrated”, when the JavaScript bundle has loaded.

There are also opportunities to use this outside of static hosting, to take the pressure off the server when generating and caching routes.

The primary benefit of pre-rendering is that you get the core content of each page with the HTML payload—regardless of whether or not your JavaScript bundle successfully downloads. It also increases the likelihood that each route of your application will be picked up by search engines.

You can read more about zero-configuration pre-rendering (also called snapshotting) here.

Filename Conventions

Jest will look for test files with any of the following popular naming conventions:

• Files with .js suffix in __tests__ folders.
• Files with .test.js suffix.
• Files with .spec.js suffix.

The .test.js / .spec.js files (or the __tests__ folders) can be located at any depth under the src top level folder.

We recommend to put the test files (or __tests__ folders) next to the code they are testing so that relative imports appear shorter. For example, if App.test.js and App.js are in the same folder, the test just needs to import App from './App' instead of a long relative path. Colocation also helps find tests more quickly in larger projects.

Now

now offers a zero-configuration single-command deployment.

1. Install the now command-line tool either via the recommended desktop tool or via node with npm install -g now.

2. Install serve by running npm install --save serve.

3. Add this line to scripts in package.json:

   "now-start": "serve build/",
   

4. Run now from your project directory. You will see a now.sh URL in your output like this:

   > Ready! https://your-project-dirname-tpspyhtdtk.now.sh (copied to clipboard)
   

   Paste that URL into your browser when the build is complete, and you will see your deployed app.

Details are available in this article.

S3 and CloudFront

See this blog post on how to deploy your React app to Amazon Web Services S3 and CloudFront.

Troubleshooting

npm start doesn’t detect changes

When you save a file while npm start is running, the browser should refresh with the updated code.
If this doesn’t happen, try one of the following workarounds:

• If your project is in a Dropbox folder, try moving it out.
• If the watcher doesn’t see a file called index.js and you’re referencing it by the folder name, you need to restart the watcher due to a Webpack bug.
• Some editors like Vim and IntelliJ have a “safe write” feature that currently breaks the watcher. You will need to disable it. Follow the instructions in “Working with editors supporting safe write”.
• If your project path contains parentheses, try moving the project to a path without them. This is caused by a Webpack watcher bug.
• On Linux and macOS, you might need to tweak system settings to allow more watchers.
• If the project runs inside a virtual machine such as (a Vagrant provisioned) VirtualBox, create an .env file in your project directory if it doesn’t exist, and add CHOKIDAR_USEPOLLING=true to it. This ensures that the next time you run npm start, the watcher uses the polling mode, as necessary inside a VM.

If none of these solutions help please leave a comment in this thread.

npm test hangs on macOS Sierra

If you run npm test and the console gets stuck after printing react-scripts test --env=jsdom to the console there might be a problem with your Watchman installation as described in facebookincubator/create-react-app#713.

We recommend deleting node_modules in your project and running npm install (or yarn if you use it) first. If it doesn't help, you can try one of the numerous workarounds mentioned in these issues:

• facebook/jest#1767
• facebook/watchman#358
• ember-cli/ember-cli#6259

It is reported that installing Watchman 4.7.0 or newer fixes the issue. If you use Homebrew, you can run these commands to update it:

watchman shutdown-server
brew update
brew reinstall watchman

You can find other installation methods on the Watchman documentation page.

If this still doesn’t help, try running launchctl unload -F ~/Library/LaunchAgents/com.github.facebook.watchman.plist.

There are also reports that uninstalling Watchman fixes the issue. So if nothing else helps, remove it from your system and try again.

npm run build silently fails

It is reported that npm run build can fail on machines with no swap space, which is common in cloud environments. If the symptoms are matching, consider adding some swap space to the machine you’re building on, or build the project locally.

npm run build fails on Heroku

This may be a problem with case sensitive filenames. Please refer to this section.

Something Missing?

If you have ideas for more “How To” recipes that should be on this page, let us know or contribute some!