Part 1 of a 2 part series on building a MERN (Mongo-Express-React-Node) app with all four CRUD actions (Create-Read-Update-Delete).
By Steve Carey - 7/9/2019
This Tutorial covers:Finished code: Github
In this 2-part tutorial series we will build a simple articles app to execute all four CRUD actions in the context of a MERN stack. Part 1 covers the API and can be done without doing Part 2.
This tutorial assumes you are familiar with JavaScript, know how to use the command line, and have Node.js installed on your computer. First your version of Node.js should be recent. To see your version, go to the command line and run node -v (returning a version means node is at least installed). Compare that to the latest LTS version from nodejs.org and upgrade if it's a major release (first digit) behind for sure.
Create a directory for your project and cd into it. We'll call it mern-app-tutorial (or whatever you want to call it).
mkdir mern-app-tutorial && cd mern-app-tutorialCreate the files for our API. You can use these UNIX commands from the command line, or do it in your text editor if you prefer. Mkdir creates a directory and touch creates a file.
touch server.js mkdir models touch models/article.js mkdir routes touch routes/index.js
Generate a package.json file. This file contains the metadata for a Node.js project. Adding the --yes flag will use the defaults for the fields.
npm init -yInstall our npm packages. First the global packages. These get installed on your system and not attached to any specific project. The Nodemon package will allow you to do hot reloading of your app, which means it will restart the server every time you make a change and save it in your project. The --global or -g flag makes it global. If you already have it installed this will upgrade it to the latest version.
npm install -g nodemonLocal packages will be installed directly in your project, in the node_modules folder. Install the following packages:
npm install express mongooseYour package.json file should look something like the below. A list of the project's installed packages with version and their dendencies is saved under dependencies. If we ran npm install then npm would attempt to install or update the packages listed there.
Make sure the "main" property's value is "server.js". Change it if it isn't.
Also make sure you have the "start" script. Add it if you don't. We can run the commands in the scripts object from the command line with npm run script-name. I'll explain more in the next section.
// package.json
{
"name": "mern-app-tutorial",
"version": "1.0.0",
"description": "Web app built with Node.js, Express, MongoDB, and React",
"main": "server.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node server.js"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"express": "^4.17.1",
"mongoose": "^5.6.6"
}
}
You will also see a file named package-lock.json. That lists all the project's installed packages with their versions and their dendencies.
Populate the server.js file with a hello world app powered by Express:
// server.js
const express = require('express');
const app = express();
const PORT = 3001;
app.get('/', function(request, response) { response.send('Hello World!') });
app.listen(PORT, function() { console.log(`Server listening on port ${PORT}`) });
This simple file, with the Express library, will create a server. There are a few different commands you can use to run it. I'll cover them briefly. First there is a standard node command to execute any file:
node server.js or just node serverThis should log "Server listening on port 3001" in the terminal, and if you open a browser to localhost:3001 you should get "hello world". To stop the server, from the terminal press CTRL+C,
NPM init generated a script to run this command in our package.json file. You call the scripts in your package.json file with npm run script-name or in a few cases "run" is optional.
npm startThe third way to execute the server.js file is to use the nodemon command. We installed nodemon for hot reloading. To use it just enter nodemon and it looks for a file named server.js to run by default. This is the command we'll use throughout this tutorial.
nodemonA quick note on syntax. Node recognizes most, but not all, ES6 syntax. Notably it does not recognize import/export statements, so we won't use them here. You have the option of installing Babel which will translate it for you. Since it's not critical to this tutorial we won't do it. Also, as default I am using the declaration syntax for functions rather than arrow functions. That just makes it consistently explicit what your function is returning or if it isn't returning anything.
MongoDB is a noSQL database. If you've only dealt with relational databases like PostgreSQL, MySQL, SQLite, etc., it's a different way of thinking about it. This tutorial won't get into how noSQL works. There are plenty of other resources for that such as mongodb.com/nosql-explained. Don't worry if you've never used it before, you can continue with this tutorial without a problem.
MongoDB offers a cloud database called Atlas, or you can download the "community version" on your local machine. You may have read about another popular cloud solution called mlabs, but they were bought by MongoDB and are no longer accepting new accounts. Which to use? I generally prefer a local version to work with in development. Sometimes there are connection issues with a cloud version (which I ran into). But if you deploy your app to Heroku then you need a cloud solution. I will explain both ways.
Quick terminology for those used to relational databases. "Collections" are like tables in a relational database and "documents" are like records.
Also, don't worry about creating the collections. Once you create the database and connect to it, MongoDB will automatically create a collection for you when you save a document to a collection that doesn't exist yet.
At the time of this writing you can set up a free account for a small project like this one at mongodb.com/cloud/atlas. It is very fast and straight-forward to set up. Just follow their steps, but note a few things:
mongodb+srv://user:password@cluster-number.mongodb.net/test?retryWrites=true&w=majority. Copy this and paste it into the server.js file (which we'll cover next).I'm on a Mac so I'll explain briefly how to load the MongoDB community version on a Mac using Homebrew. If you are on windows, installation instructions are at docs.mongodb.com/manual/tutorial/install-mongodb-on-windows.
To see if MongoDB is installed on your machine with Homebrew run:
brew list mongodb or brew search mongodbIf it's installed it will show the path of any MongoDB executable files (there are several). If it's not installed run:
brew install mongodbNow set up the directory where the database is stored. MongoDB expects you to use data/db so we'll go with that:
sudo mkdir -p data/dbAnd set the owner of this directory to yourself.
sudo chown -R $(whoami) data/dbSudo means Super User Do. You need that for commands that require super user permissions like messing around with you Mac's root directory. Chown means change owner. The -R flag makes this recursive meaning it changes the owner of all the files and folders in the directory. $(whoami) runs the UNIX whoami command to get your username on your computer.
If MongoDB was already installed you can check to see if the version is outdated.
brew outdated mongodbThis will return your version compared to the latest version if they differ. If it returns nothing then you have the latest version. You can upgrade the MongoDB version with:
brew upgrade mongodbOnce it's installed you run MongoDB from the terminal (from any directory) and have to leave that window open and running to access the database:
mongodStop MongoDB from the same terminal window with CTRL+C.
You can interact with the database directly using the MongoDB shell from the Terminal. There are also GUI tools like Robo T3 if you prefer that but frankly for small projects I find the command line easier to work with. To use the shell from anywhere in the terminal run:
mongoThe list of MongoDB commands are at docs.mongodb.com/manual/reference/mongo-shell and CRUD Operations. Useful commands include:
show dbs - Returns a list of your databases.use my_local_db - Use the specified database. Creates it if it doesn't exist.db - Returns the db you are currently in.show collections - Returns the collections in the db you are currently in. Collections are like tables in an SQL database.db.createCollection("articles") - Create a collection.db.articles.find() - Show all documents in the collection. Documents are like records in an SQL database.db.articles.insertOne( { title: "Learn MongoDB", content: "Lorem Ipsum." } ) - Insert a document into a collection. Must use double quotes for a string.db.articles.find({title: "Learn MongoDB"}) - Returns all that match the condition.db.articles.findOne({title: "Learn MongoDB"}) - Returns the first document that matches the condition.db.articles.findOne({"_id" : ObjectId("id-string-here")}); - Find by id.db.articles.updateOne({title:"Learn MongoDB"},{ $set: {content:"Blah Blah."}}) - Updates a specific field in a document. Adds document if it doesn't exist. Use updateMany() for multiple.
db.articles.update({"_id" : ObjectId("id-string-here")},{ $set: {content:"Blah Blah Blah!"}}) - Find by ID then update.
db.articles.deleteOne( { title: "Learn MongoDB" }) - Remove one document by non-id field. Use deleteMany() for multiple.db.articles.deleteOne( { "_id": ObjectId("value") }) - Remove by id.db.dropDatabase() - Deletes the db you are currently in.We installed the mongoose package in our app. Mongoose is a middleware library that performs the Object Relational Mapping (ORM) between our Express application and MongoDB. In essence it does the translations allowing them to talk to each other.
We'll start by using Mongoose to connect to MongoDB in our server file. Let's replace the hello world response with our real code and then we'll go through it line by line.
// server.js const express = require('express'); #1 const mongoose = require('mongoose'); // const cors = require('cors'); const router = require('./routes/index'); const app = express(); #2 const PORT = 3001; #3 const MONGODB_URI = "mongodb://localhost:27017/my_local_db"; #4 // app.use(cors()) app.use(express.urlencoded({ extended: true })); #5 app.use(express.json()); app.use('/api', router); #6 mongoose.connect(MONGODB_URI, { useNewUrlParser: true, useFindAndModify: false }); #7 mongoose.connection.once('open', function() { #8 console.log('Connected to the Database.'); }); mongoose.connection.on('error', function(error) { console.log('Mongoose Connection Error : ' + error); }); app.listen(PORT, function() { #9 console.log(`Server listening on port ${PORT}.`); });
express.urlencoded({ extended: true }) and express.json() are middleware for parsing requests with JSON payloads (for POST and PATCH/PUT requests).mongoose.connect() connects to our MongoDB databaseLet's talk briefly about Cross-Origin Resource Sharing (CORS). By default Express will block cross-origin HTTP requests for security reasons. Cross-origin means the request is from a different origin (domain, protocol, and/or port) than its own origin. Our API is served on localhost port 3001. If our API is accessed by mobile apps for example they will be on a different origin and any requests will be rejected. There is an npm package called cors that will apply additional HTTP headers to tell the browser to allow access from a specified origin or any origin.
A standard MERN app is really an integrated single web application even if the back end and front end run independently. We only want to give access to the integrated front end (our React client in this case) and therefore won't use the cors package. There's an additional step when we build the React app that we'll cover there.
If, however, your API is meant to be accessed by mobile apps or other websites then you need to install the cors middleware package and connect it to your app.
npm install corsThe server.js file comments out the cors package import and where it is applied to the app. To allow cross origin access uncomment those lines.
For more on the CORS concept see developer.mozilla.org/en-US/docs/Web/HTTP/CORS
Populate the model file with the below:
// models/article.js const mongoose = require('mongoose'); const articleSchema = new mongoose.Schema({ #1 title: { type: String, required: [true, "Title is required"] }, content: { type: String, required: [true, "Content can't be blank"] } }); module.exports = mongoose.model('Article', articleSchema); #2
Now that we have our server, database and model set up, the last step for our simple API application is routing. Routing refers to determining how an application responds to a client request to a particular endpoint. An endpoint is a combined URI and HTTP request method (GET, POST, PATCH or PUT, DELETE) that activates specific actions from our API.
We will apply database Create, Read, Update, and Delete (CRUD) actions to each endpoint. Meaning we will have an endpoint to return (Read) a JSON array of all our articles and another endpoint to return (Read) a JSON object for a specified article id. We will also have endpoints to Create, Update, and Delete articles. So our routes will be "RESTful" which essentially means our application routes and actions are build around performing these database CRUD actions.
Populate the routes file:
// routes/index.js const express = require ('express'); const router = express.Router(); #1 const Article = require('../models/article'); #2 router.get('/articles', function(req, res) { #3 Article.find(function(err, articles) { res.json(articles); }); }); router.get('/articles/:id', function(req, res) { #4 Article.findById(req.params.id, function(err, article) { if (!article) { res.status(404).send('No result found'); } else { res.json(article); } }); }); router.post('/articles', function(req, res) { #5 let article = new Article(req.body); article.save() .then(article => { res.send(article); }) .catch(function(err) { res.status(422).send('Article add failed'); }); }); router.patch('/articles/:id', function(req, res){ #6 Article.findByIdAndUpdate(req.params.id, req.body) .then(function() { res.json('Article updated'); }) .catch(function(err) { res.status(422).send("Article update failed."); }); }); router.delete('/articles/:id', function(req, res) { #7 Article.findById(req.params.id, function(err, article) { if (!article) { res.status(404).send('Article not found'); } else { Article.findByIdAndRemove(req.params.id) .then(function() { res.status(200).json("Article deleted") }) .catch(function(err) { res.status(400).send("Article delete failed."); }) } }); }) module.exports = router; #8
For each API endpoint we will chain a method to the router object. The format is:
router.HTTP Method(path, handler function)
We imported the Article model representing the articles collection in our database. We chain methods from the mongoose library to the Article prototype that will perform different types of CRUD actions. Our handler functions perform the CRUD operation and may return a response. Generally only return responses that will be used by the client.
In the server.js file we imported our router object and then chained it to our Express app object. The first argument '/api' applies our router object when the '/api' path is called.
// server.js
const router = require('./routes/index');
...
app.use('/api', router);
If you are familiar with the Model-View-Controller pattern (MVC) commonly used by web app frameworks, Express uses that pattern as well. Model we talked about. We are combining the controller actions directly with the routes rather than separating them into separate route and controller files. The view will be our React front end. Or you may say our view is the JSON responses returned when accessed by our front end React app. Let's see those in action.
With all the changes it's best to just restart your server:
nodemonThen in your browser go to the API articles endpoint:
http://localhost:3001/api/articles
And you should see an empty array. Congratulations! All that hard work paid off. An empty array. Now lets test all the endpoints using Curl and/or Postman.
We're not done with our API until we know all the endpoints we created work. I'll discuss two ways we can do this. First is using Curl.
Curl is a command line utility that lets you make HTTP requests from the Terminal instead of from a web page. Curl comes preloaded with Macs. For Windows you may need to install it, but it's a handy tool sometimes. Let's make a POST request by entering the below Curl command. The -H option is for the header which is where we tell the receiver that the data we are sending is in JSON format. The -X option specifies the request method, POST in this case. The -d option is where we put our data, so you won't use the -d option with GET or DELETE requests. And of course we include the URL.
nodemon Make sure you start the server if it's not already runningcurl -H "Content-Type: application/json" -X POST -d '{"title":"Learn MERN","content":"Lorem Ipsum."}' http://localhost:3001/api/articles
If it posted the server should send a response back with the new Article data in JSON format. It will have the title and content fields as you submitted, but it will also have an autogenerated _id field. If you go back to your browser localhost:3001/api/articles and refresh it, your empty array should now have one article in it.
You can also make a Curl GET request with the new ID:
curl -X GET http://localhost:3001/api/articles/article._id - inserting the _id.
Now let's update this record with a PATCH request:
curl -H "Content-Type: application/json" -X PATCH -d '{"title":"Learn the MERN Stack","content":"Lorem ipsum."}' http://localhost:3001/api/articles/article_id
It returns a JSON string of the saved updated article data. Now, let's delete it:
curl -X DELETE http://localhost:3001/api/articles/article._id
If you don't like the cryptic feel of sending HTTP requests from the command line, there is a popular free desktop application called Postman that lets you do the same thing from a GUI interface. You can download it from getpostman.com. The tool is fairly intuitive but you will need to play around with it a bit to get comfortable with it. If you plan on building a lot of APIs Postman is an essential tool. Here are the CRUD actions hitting our API's endpoints:
If everything works then our simple API is done! We can use this API as the back end for a mobile app, or to be accessed by other websites to display our fabulous articles. Or we could integrate it with a front end library like React to make a fully functioning web application. A so-called single-page-app (SPA). To do that last one, go on to part 2: MERN APP: Integrate React.