MongoDB Stitch now provides GraphQL APIs to access your data. This tutorial walks through a simple TODO application in which users can create, read, update, and delete tasks using GraphQL.
Before the React application can be run, MongoDB Atlas and Stitch must be configured.
A MongoDB Atlas cluster is needed for the application (skip this section if you already have one which can be used.). Follow this tutorial to create an Atlas cluster.
For this tutorial an "M0", our free-forever instance, is sufficient.
From the Atlas UI lets create a stitch app, follow the instructions found here.
Take note of the application id (APP ID), this will be required later for application configuration.
NOTE: during this configuration process, we can wait till the end to review and deploy all changes, but I would recommend deploying as each step is performed. Alternatively, turn off "Drafts" under the "Deploy/Configuration" Stitch tab.
While creating the Stitch application be sure to link to the cluster created above. If using an existing Stitch application, the database cluster must be linked to that app, following these instructions.
The frontend application requires anonymous authentication, set this provider up using the instructions found here
This allows our application to create a user object containing an auth token to be used by GraphQL to create, modify, and read data. This is the minimal level of authentication to work with Stitch – a production application would use a more robust method such as username/password, JSON Web Tokens, or 3rd-party authentication providers such as Google, Facebook or Apple.
For users to access data held in Atlas, a Stitch Rule must be added for the collection that will hold the data. For this tutorial, use the simple template where an authenticated user can read and write just their own data only by following these instructions.
Select the demo
database and the task
collections, the rule will be applied to this collection only.
The template to use is Users can only read and write their own data
, for the "field name for the user id" section enter owner_id
.
Next, we will need to create a schema for our collection, that is used in the GraphQL API.
Since we don't have any documents in our collection we cannot use a sample to generate the schema, or validate the existing schema against existing data.
Use these instructions to define the schema:
{
"properties": {
"_id": {
"bsonType": "objectId"
},
"name": {
"bsonType": "string"
},
"description": {
"bsonType": "string"
},
"tags": {
"bsonType": "array",
"uniqueItems": true,
"items": {
"bsonType": "string"
}
},
"owner_id": {
"bsonType": "string"
},
"createdAt": {
"bsonType": "date"
},
"active": {
"bsonType": "boolean"
},
"modifiedAt": {
"bsonType": "date"
},
"archived": {
"bsonType": "boolean"
},
"archivedAt": {
"bsonType": "date"
},
"finished": {
"bsonType": "boolean"
},
"finishedAt": {
"bsonType": "date"
},
"dueBy": {
"bsonType": "date"
},
"recurringTask": {
"bsonType": "boolean"
},
"recurringDate": {
"bsonType": "date"
}
}
}
NOTE: Not all the fields are currently being used.
Please remember to review and deploy the changes to take effect.
At this point, the Stitch application is providing the GraphQL API,
From the Stitch UI, go to the GraphQL
menu (found on the left hand side), this will bring up the GraphQL editor and documentation explorer.
Using the documentation and the UI various queries can be tested here. Because we are entering queries in the Admin UI, the owner_id
attribute is not needed.
Take a note of the GraphQL endpoint listed on that screen.
This is optional but if you want to host your react application on the Stitch Platform, see enable static hosting for the frontend web assets.
This will create a secure URL that can be used to access the react web application.
NOTE: Please note that because this application uses anonymous authentication, we strongly recommend to not host this application for too long as anyone with the URL can access the application and login anonymously to create data on your system.
It is assumed your development environment is setup to run Node.js.
Clone this repo, copy the env.local
file to .env.local
, and add the stitch app id and GraphQL endpoint to the environment variables.
If these variables change at any point, you will need to restart the application for the changes to take effect.
Run yarn install
to install the required node modules.
Run yarn start
, this will start the development server and open a browser tab running the applcation.
It is recommended to install the React development tools for the browser and open the development console to help troubleshoot any issues.
Any GraphQL issues will be logged as errors to the development console.
Once the application has been tested and you want to create a build, run yarn build
to create a build directory, the contents of this directory will need to be uploaded to Stitch hosting (or your choice of web host).
Follow the instruction found here to updload the React application to stitch. Once the files have been deployed, the application is available at the URL shown on the Stitch hosting page.
As this tutorial is solely focused on GraphQL, anonymous authentication has been used to reduce friction.
Don't host for too long if your concerned about others writing tasks to your task
collection.
If you have any issues with the setup or find any bugs please open an issue and we will address them as soon as possible.
We also pull requests, if you feel like adding features or fixing bugs you find, issue a pull request and we will review it and work with you to get it merged.