AB-APP2 is an AWS serverless boilerplate application. It is written in JavaScript (React) and Node.js. It uses GraphQL, AWS AppSync, and AWS Lambda. It can be a starting point for your own applications.
If you don't need real-time and offline functionality have a look at AB-APP (this is the API Gateway version of the same boilerplate).
This boilerplate application is an app of the fictional "Scientific Research Institute of Sorcery and Wizardry" from the famous novel by Boris and Arkady Strugatsky "Monday Begins on Saturday". AB-APP2 exposes a list of institute's departments for authenticated users. It allows to add and edit departments.
You can see AB-APP2 in action here. Current version is deployed without AWS CloudFront for simplicity, but when running a production app, consider using CloudFront to speed up. Also note that when visiting the link for the first time, application may load slowly. This is because of the lambda cold start. In production warm up dump requests should be used to keep your lambda in a warm state.
- Current status
- Architecture
- Features implemented
- Local development
- Authorization
- Real-time data
- PWA and offline
- Testing
- Deployment
- Bit
- TODO
- How to contribute
AB-APP2 is still under development. It is not finished!
Feel free to experiment with it, but don't use it in production as is!
The application uses RDS/DynamoDB and S3 for persistent storage. A single lambda function holds all the backend logic. AWS AppSync is used to connect frontend with backend.
The application has two main folders: backend and frontend. These folders hold source code of the backend and the frontend respectively.
- Authorization and authentication using JWT tokens + tokens refresh
- Tables for viewing data with pagination, row selection, sorting and CSV export
- Forms for adding and editing data with live, backend-frontend consistent validation.
- Install a database (MariaDB), Node.js, NPM, docker, aws-sam-cli and Redux DevTools extension
- Git clone or download the project's source
- Run
npm installboth in the frontend and backend folders - Import mysql.dump.sql into your MariaDB instance
- Create
backend/.envfile with the following content (replace DB_HOST with IP of your local DB instance):
#Environment
PROD=false
#Token secret
SECRET="SOME_SECRET_CODE_672967256"
#DB
DB_HOST="XXX.XXX.XXX.XXX"
DB_NAME="abapp"
DB_USER="abapp"
DB_PASSWORD="abapp"
- Create
frontend/.envfile with the following content
REACT_APP_LOCAL_APPSYNC_URL=http://localhost:4000
For now aws-sam-cli doesn't support AppSync (see #551). So we've built a Node.js script, which works like local AppSync (appsync-local.js). This script uses JS-YAML and Velocityjs to read definitions and velocity mapping templates from the project's CloudFormation template and GraphQL Schema. Then it creates Apollo Server, to resolve GraphQL queries and mutations, and call local Lambda enpoint.
Subscriptions are not fully supported yet, but we are working on that.
- Run docker and then run
sam local start-lambdain the root folder of the project to start local Lambda (set --docker-volume-basedir parameter to your root dir, if you use remote docker) - Run
npm startin the backend folder to start local AppSync. - Run
npm startin the frontend folder to start webpack development server - Have fun! 😃
AB-APP2 AppSync client is authorized using AWS_IAM auth type. But this first auth layer simply allows access to AppSync API for all anonymous users. It is handled by AWS Cognito federated identity pool with enabled unauthenticated access.
Actual authorization of AB-APP2 users is based on JWT tokens. Bearer token is passed along side with cognito tokens in x-app-token header with every request. All auth logic is handled by the backend Lambda code.
- DynamoDB support
- Subscriptions and Real-Time features
- PWA features and offline functionality
- Click the "Fork" button.
- Clone your fork to your local machine:
git clone https://github.com/YOUR_USERNAME/ab-app.git- Add 'upstream' repo to keep your form up to date:
git remote add upstream https://github.com/gnemtsov/ab-app2.git- Fetch latest upstream changes:
git fetch upstream- Checkout your master branch and merge the upstream repo's master branch:
git checkout master
git merge upstream/master- Create a new branch and start working on it:
git checkout -b NEW_FEATURE- Push your changes to GitHub.
- Go to your fork's GitHub page and click the pull request button.