React Ionic PWA Starter
Prerequisites
- NodeJS LTS (Download - Required)
- Docker (Download - Only required for serverless deployment on MacOS and Windows)
- MongoDB Community Server (Download - Optional)
- You can use a service such as mLab instead. See the
MONGO_URL
secret.
- You can use a service such as mLab instead. See the
Using this repository as a starter
Clone the project using git:
git clone -b master --single-branch https://github.com/kgroat/react-ionic-pwa-starter.git my-pwa
- Clone themaster
branch into a folder namedmy-pwa
rm -rf .git
- Get rid of the git data associated with the original repositorygit 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 remotegit 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
- This is also used as the database name if no
appName
- The title for you application (Used in the<title />
tag of your PWA)pushEmail
- The email used for registering push notifications, in amailto:
urlnoreplyEmail
- The default email used when sending throughnodemailer
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 yourpackage.json
) - Update / remove the badges (Serverless, CircleCI, Coveralls)
- Remove this section ("Using this repository as a starter")
- Update the title (should be the same as
- In
src/static/mainifest.json
, update:name
- Should be the same asappName
from yourpackage.json
short_name
- This is what the app's name will show up as when installed on a devicegcm_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 replacebadge.png
,icon.png
, andfavicon.ico
- NOTE:
favicon.ico
can be generated from a 512x512icon.png
in this directory using thenpm run icon
command
- NOTE:
- You can store large asset files in the
- If you're not using CircleCI, you will want to remove the
circle.yml
file at the root of the project
Quickstart
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 modenpm run serverless:prod
- deploys to prod stage in production modeBASE_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
Project Secrets
In order to run, build, or deploy the application, you'll need to supply some secrets.
NOTE: These secrets SHOULD NOT be committed into your repository.
The secrets / environment variables will live in a few different places:
- A
.env
file at the root of the project for local development (used when runningnpm run start:dev
ornpm run build
)- Use the
dotenv
format
- Use the
- A
secrets.yml
file at the root of the project (used when deploying usingnpm run serverless:*
commands)- See
example-secrets.yml
for an example of what this file should look like
- See
- Your CircleCI environment variables (if you use CircleCI)
Secrets include:
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 themongod
instance you want to connect to.- Leave this out of your
.env
file if you just want to connect to a locally-runningmongod
instance - You can use a service such as mLab to host a database, if you want a remote database instead.
- Leave this out of your
TRANSPORT_AUTH
- (Required for production) A JSON string used as the authentication fornodemailer
in production mode.- In development mode, Etherial Email is used, and the resulting URLS logged to
STDOUT
.
- In development mode, Etherial Email is used, and the resulting URLS logged to
Other environment variables include:
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 yourBASE_URL
variable during deployments instead.
- If not provided, defaults to
PASSWORD_SALT_ITERATIONS
- (Reccommended) The cost number forbcrypt
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 exceptproduction
, development mode is enabled.- Defaults to
development
- Defaults to
Development mode
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
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.
Generators
To create a new React container:
npm run generate:container [ContainerName]
- Note: the word
View
will automatically be appended to yourContainerName
- Note: the word