• NodeJS LTS (Download - Required)
• Docker (Download - Only required for serverless deployment on MacOS and Windows)
  • If you are on MacOS / Windows, ensure that your development directory is mountable by docker
  • See the documentation for MacOS or Windows
• MongoDB Community Server (Download - Optional)
  • You can use a service such as mLab instead. See the MONGO_URL secret.

Clone the project using git:

• git clone -b master --single-branch https://github.com/kgroat/react-ionic-pwa-starter.git my-pwa - Clone the master branch into a folder named my-pwa
• rm -rf .git - Get rid of the git data associated with the original repository
• git init - Re-initialize the directory as a local git repository

From there, you can add your own remote and push the code:

• git remote add origin [your-repo-url] - Add your own repository as the origin remote
• git commit -m 'Initial commit' && git push -u origin master - Create and push your initial commit

Before you do, you will want to update project details:

• In package.json, you'll want to update:
  • name - a unique identifier (should be kebab-case)
    • This is also used as the database name if no MONGO_URL secret is specified
  • appName - The title for you application (Used in the <title /> tag of your PWA)
  • pushEmail - The email used for registering push notifications, in a mailto: url
  • noreplyEmail - The default email used when sending through nodemailer
  • description - A brief description of your project (Optional)
  • bugs, homepage, repository - The issues, readme, and repository url (respectively) to your repo (Reccommended)
• In README.md:
  • Update the title (should be the same as appName from your package.json)
  • Update / remove the badges (Serverless, CircleCI, Coveralls)
  • Remove this section ("Using this repository as a starter")
• In src/static/mainifest.json, update:
  • name - Should be the same as appName from your package.json
  • short_name - This is what the app's name will show up as when installed on a device
  • gcm_sender_id - If you're using GCM or FCM keys for push notificaitons (You do NOT need to add firebase to the project for this to work)
• Update your static image assets
  • You can store large asset files in the assets directory -- it currently houses the source icon Photoshop document
  • In src/static, you'll want to replace badge.png, icon.png, and favicon.ico
    • NOTE: favicon.ico can be generated from a 512x512 icon.png in this directory using the npm run icon command
• If you're not using CircleCI, you will want to remove the circle.yml file at the root of the project

To set up:

• npm install

To run locally in development mode with hot module replacement (in app and server code) enabled:

• npm run start:dev

To run the tests:

• npm test

To test a static production mode bundle locally:

• npm run build && npm start

To run in production mode with hot module replacement (in app and server code) enabled:

• NODE_ENV=production npm run start:dev

To build and deploy to AWS Lambda on MacOS or Windows (Docker required):

• npm run serverless:dev - deploys to dev stage in development mode
• npm run serverless:prod - deploys to prod stage in production mode
• BASE_URL='/stage/' STAGE='stage' NODE_ENV='production' npm run serverless:docker - deploy to specified stage with specified base URL, optionally in production mode

To build and deploy to AWS Lambda on linux:

• BASE_URL='/stage/' STAGE='stage' NODE_ENV='production' npm run serverless:linux - deploy to specified stage with specified base URL, optionally in production mode

If you want to use a specific AWS profile to deploy, simply specify the AWS_PROFILE environment variable:

• AWS_PROFILE='myProfile' npm run serverless:dev

To run a production build using serverless offline, run:

• npm run serverless:offline

In order to run, build, or deploy the application, you'll need to supply some secrets.

• A .env file at the root of the project for local development (used when running npm run start:dev or npm run build)
  • Use the dotenv format
• A secrets.yml file at the root of the project (used when deploying using npm run serverless:* commands)
  • See example-secrets.yml for an example of what this file should look like
• Your CircleCI environment variables (if you use CircleCI)

• AUTH_SECRET - (Required) The secret used for encrypting and decrypting JWT tokens, used for user authentication
  • NOTE: It is reccommended to use a long (~128 characters), randomly-generated string. You can use a random generator such as random.org and concatenate the results together.
• FCM_KEY - (Optional) Used for registering push notification clients, if using GCM or FCM keys for push notificaitons (You do NOT need to add firebase to the project for this to work)
• MONGO_URL - (Required for production) The URL (including database name) of the mongod instance you want to connect to.
  • Leave this out of your .env file if you just want to connect to a locally-running mongod instance
  • You can use a service such as mLab to host a database, if you want a remote database instead.
• TRANSPORT_AUTH - (Required for production) A JSON string used as the authentication for nodemailer in production mode.
  • In development mode, Etherial Email is used, and the resulting URLS logged to STDOUT.

• BASE_URL - (Optional) The base URL for the application. serverless uses AWS API Gateway, which sets the base URL to be the same as the stage name.
  • If not provided, defaults to /.
  • This default works fine for local development; it may also work for production, if you use a custom domain name with a base path of /. If you use a base path other than /, specify that path as your BASE_URL variable during deployments instead.
• PASSWORD_SALT_ITERATIONS - (Reccommended) The cost number for bcrypt key expansion used when hashing and checking passwords.
  • If not provided, a default of 10 is used.
  • NOTE: The default is fine for local development, but may not be sufficient for production environments (reccomended reading).
  • Here is a list of general estimates of cost factors on
• NODE_ENV - (Optional) If this is anything except production, development mode is enabled.
  • Defaults to development

When NODE_ENV is anything besides production, development mode is enabled. In development mode, the global variable __DEV__ is set to true for all code (app, server, serviceWorker). You can use this variable to ensure that portions of your code is only executed in development mode. By default, development mode is active during local development using npm run start:dev.

NOTE: Unit tests are also run in development mode.

Production mode is triggered by setting the NODE_ENV environment variable to production. In production mode, the global variable __DEV__ is set to false for all code (app, server, serviceWorker). To test production mode locally, run npm run build && npm run start to make a static build or NODE_ENV=production npm run start:dev for a hot-reloaded build.

To create a new React container:

• npm run generate:container [ContainerName]
  • Note: the word View will automatically be appended to your ContainerName