Skip to content

Latest commit

 

History

History
208 lines (148 loc) · 11.1 KB

documentation.md

File metadata and controls

208 lines (148 loc) · 11.1 KB
Raw

Table of Contents

AEBoilerplate is a full-stack React/Node/Typescript web project starter that focuses primarily on ease-of-use and simplicity.

Boilerplate structure

The boilerplate is divided into two independent applications - the client and API. As the boilerplate is not a monolithic application, the client and API can be separated into their own repositories.

The client application is generated using create-react-app and the API is built on top of Node and Express with a Postgres database.

Both applications come preconfigured with Docker and Docker Compose for running the applications locally in self-contained environments.

Here is a basic overview of the structure and technologies used:

Development

The boilerplate comes packaged with a docker-compose file preconfigured for hot-reloading.

npm run dev

Running the command above in the root directory starts Docker-ized instances of the client, API, and database.

Available scripts

To see all available npm scripts, run:

npm run

Configuration

The API and client configuration files share the same structure and can be found in their respective /src/config folders. In a development environment, values are referenced inside the docker-compose configuration files.

Authentication

Google

  • Create a new project from your Google developer page.
  • After creating your project you are redirected to the project Dashboard. Enable Google+ API by clicking on the Library link on the left menu and searching for Google+ API or ENABLE APIS AND SERVICES on the dashboard screen.
  • Go to the OAuth consent tab by clicking on the credentials link on the left menu. Click on CREATE CREDENTIAL:
    • Which API are you using?
      • Google+ API
    • Where will you be calling the API from?
      • Web server (e.g. node.js, Tomcat)
    • What data will you be accessing?
      • User data
  • After adding this information click on What credentials do I need?
  • It'll open the second step to create an OAuth 2.0 client ID:
    • Name : your application name
    • Authorized JavaScript Origins: http://localhost:3001
    • Authorized Redirect URIs: http://localhost:3001/auth/google/callback
  • Click on Create OAuth client ID.
  • The third step will open for the consent screen configuration where you need to set your product name. Click on continue after setting the product name.
  • In the last step, click on Done. You will be able to copy the client id on the next screen.
  • Click on your project name. Copy the Client ID and Client Secret to GOOGLE_ID and GOOGLE_SECRET in both the root level and API docker-compose configuration files.

Facebook

  • Create a new Facebook developer account.
  • Click on My Apps and add a new app.
  • Set a display name and your contact email.
  • Click on the Set Up button under the Facebook Login card on the main dashboard.
  • Go to Valid OAuth Redirect URIs and add http://localhost:3001/api/auth/facebook/callback.
  • Click on Save Changes
  • Copy the client id and client secret from the left menu opening the Settings item and clicking on Basic
  • Set these values to FACEBOOK_ID and FACEBOOK_SECRET in both the root level and API docker-compose configuration files.

LinkedIn

  • Create a new application from your LinkedIn developer page.
  • Set your LINKEDIN_ID and LINKEDIN_SECRET in both the root level and API docker-compose configuration files.
  • Set the LINKEDIN_CALLBACK_URL to http://localhost:3001/api/auth/linkedin/callback inside your LinkedIn application settings.

Adding other authentication methods

While the boilerplate’s API was built to use Google, Facebook and LinkedIn’s authentication strategies, it is also easy to integrate other strategies.

First, read the PassportJS documentation. Then, make the following changes:

The authentication process is using the boilerplate API and it should be easy to add other strategies changing the following files:

  • passport-initializer
    • Update the configuration file with API keys and other configurations required for your strategy.
    • Update the initializePassport function to in initialize your new strategy.
  • authenticate.ts (contains routing for your new strategy)
    • Add routes for your service.
    • Note: when following O Auth2’s authentication pattern, two paths are required - one for the initial authenticate call and another for the callback. Make sure to use the same name that was set in the passport-initializer file, e.g. passport.authenticate('facebookProvider').

Once everything has been configured, the boilerplate should automatically persist user authentication data to the database and save the token in the local storage.

Protecting your routes

If you want to create a new protected route follow these steps:

API

Add the ensureAuthenticated middleware when creating your route, e.g.

router.use('/', asyncHandler(ensureAuthenticated), (_, res) => res.send('AUTHENTICATED').status(200))

The asyncHandler is a simple middleware for handling exceptions inside of async express routes and passing them to your express error handlers.

Client

Add your route to ProtectedRoutes.tsx.

Deployment

The boilerplate can be deployed in any cloud service provider of your choice. For simplicity and ease-of-use, we use Heroku as our cloud service.

Setting up your Heroku application

Prerequisites:

  1. In your project directory, run heroku login and enter your credentials.
  2. Run heroku create APP_NAME to create your Heroku application. Copy your application URL for later steps.
  3. Navigate to your application in the heroku apps dashboard and go to the Resources tab. Under Add-ons, add a postgres database by searching for postgres in the search field. A DATABASE_URL configuration variable is generated upon creation.
  4. Navigate to your application's Settings tab in your heroku dashboard. Click on Reveal Vars and set the following values:
    • GOOGLE_ID: the client ID for your application's
    • GOOGLE_SECRET: the client secret for your Google app
    • GOOGLE_CALLBACK_URL: https://[YOUR_HEROKU_APPLICATION_URL].herokuapp.com/api/auth/google/callback using the URL from step 2.
      • If you missed your application URL on step two, go down in the Settings tab and look for the Domains and certificates item.
    • SUCCESS_LOGIN_REDIRECT_URL: https://[YOUR_HEROKU_APPLICATION_URL].herokuapp.com/connect

Deploying to Heroku

Deploy your application to Heroku by running:

git push heroku master

Continuous integration

The boilerplate uses CircleCI for automated deployment to Heroku when pushing to your Github master branch.

Setting up continuous integration with Circle CI and Heroku

Prerequisites:

  1. Uncomment the deploy step inside .circleci/config.yml.
  2. Replace the placeholder HEROKU_APP_NAME inside .circleci/deploy-heroku.sh with your Heroku application name.
  3. Navigate to the Add Projects tab and click on Set Up Project for your project.
  4. Select Linux as the operating system and Node as language. Then start building the project to launch the project on CircleCI.
  5. Settings > Projects > Go to your followed project and select the gear icon
  6. Navigate to Checkout SSH Keys under Permissions in the left menu pane. Authorize your Github to add create a user key for your account.
  7. Navigate to Heroku Deployment under Continuous Deployment and enter your Heroku API key, which can be found in your Heroku account settings. Then, set the user to your Heroku account.

Testing

The boilerplate comes with tests for both the API and client. We highly encourage you to maintain them during development.

You can find API tests in the api/spec folder and the client tests inside each React components folder.

To run client-side tests,

npm run client-test

To run server-side tests,

npm run api-test-watch