fieldfirst-again v0.3.0

fieldFirst

This is the main web app, focused around selling and distributing seed. Its target audience includes:

1. Salespeople (DSMs) - see customer needs, initiate conversations, manage relationships (CRM)
2. Growers - make agronomic decisions, order and return seed
3. Dealers - CRM, order and return seed

Technologies

It needs to run on any phone (iPhone or Android), with limited connectivity — that is, out in a field.

Progressive Web Apps

We're in luck — mobile web can do most of what we need. This is a "Progressive Web App" (PWA) — as described by Google, Mozilla, and Microsoft.

TODO: list PWA deficiencies

• background notifications
• iOS / Android differences

In short, it works in a mobile browser, a desktop browser, or behaving like an App, as supported by phone OSes. Android support is pretty strong, and iOS improved support in March 2019. Here's a comparison between iOS and Android from March 2018 that's still pretty accurate.

Google Maps / React / TypeScript

We chose Google Maps over MapBox because its imagery seems to stay more up to date — which is important for viewing field layouts.

• Google Maps — via the adapter react-google-maps
• React with TypeScript, bootstrapped with Create React App.

Getting Started

Engineering Guide

See our React Engineering Guide for guidance on Global State, Components, Actions, and Reducers.

Local Development

Install npm (yarn works too) and run:

npm install

Then, 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 — ready to be deployed!

To serve a production build locally, npm install -g serve then npm run build && serve -s build -l 4000. Two problems, though, that are easily fixed locally:

• The production API key is locked to certain websites. Substitute the development key instead (see .env.development and .env.production).

• Change homepage to "." in package.json.

Docker

The scripts docker-dev.sh and docker-prod.sh both use Dockerfile to build nginx-based containers to serve the static React files. They even fail if the tests break!

• docker-dev.sh — uses the dev API key that will run anywhere but shouldn't be published. Builds a docker image locally.
• docker-prod.sh — uses the prod API key that is locked to dev.samwise.link. Also pushes the image to a repository if you are logged into one.

They've primitive and will probably change, but at least they allow building without installing any tools besides docker.

Further Reading

react-google-maps demos

The docs' examples are broken because their Google Maps key has been deleted. To run the demos locally using styleguidist:

1. git clone git@github.com:tomchentw/react-google-maps
2. replace the API keys in the examples
3. npx styleguidist server
4. open a browser to localhost:6060

PWAs & UX

• Alex Russell's What, Exactly, Makes Something A Progressive Web App (2016, with timeless UX advice). Alex is a Chrome developer and early champion of PWAs.

• Owen Campbell-Moore's Designing Great UIs for Progressive Web Apps — more high-level advice.

• Elisabeth Morant's Google IO talk Asking for Permission: respectful, opinionated UI — how to ask for permissions in such a way that users say "Yes", and related principles such as allowing the user to revoke a permission and handling failure gracefully.

• Lighthouse — website auditing tools build into Chrome.

React

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.