Chapter 5: Getting Started with Express
In this chapter, you’ll create a web server application that constructs and returns simple web pages. It will help you become more familiar with:
- npm (Node Package Manager)
- ES6 modules
- the Express framework
- URL routing
- HTML template engines
Why use Express?
You created a small web server application in Chapter 3. It’s fast, and it works well, but a complex web application requires features such as URL routing, query string parsing, posted data decoding, HTML templates, image serving, and more. You could write this yourself, but much of that effort is already implemented in Express.
Express is a Node.js web server framework that promotes itself as “fast, unopinionated, and minimalist”. It allows you to concentrate on your application’s business logic without having to worry too much about web server technicalities such as URL routing, parsing data, setting HTTP headers, and so on.
Various web server frameworks are available in the Node.js ecosystem, including Fastify, Koa, and Hapi. These may be more recent, more regularly maintained, faster, and a better fit for your application. However, Express was one of the first web frameworks and influenced all that followed. It’s stable, easy to use, and remains popular, with 18 million downloads per week. You’re more likely to encounter Express than another framework.
Express Version
At the time of writing, Express 4 is the active recommended release and Express 5 is in alpha. All the examples below should work in either, but switch to version 4 if you have problems.
Create a New Node.js Project
Create and access a project directory for your new application. A name such as express is fine:
mkdir express
cd express
Create a New Git Repository
For real projects, I recommend creating a new Git repository and cloning it accordingly. This is easier than attempting to Git-ify a partially written project later.
Run npm init to initialize a new Node.js project. npm will prompt you for values, but you can hit Enter to accept the defaults.
npm saves the settings to a new package.json file in your project’s root directory:
{
"name": "express",
"version": "1.0.0",
"description": "Example Express app",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Craig Buckler",
"license": "MIT"
}
package.json provides a single place to configure your application. It contains the name, the version, the main entry/starting script, useful application scripts, configuration data, and module dependencies.
Semantic Versioning
Most Node.js projects use semantic versioning, with three MAJOR.MINOR.PATCH numbers such as 1.2.33. When a change occurs, you increment the appropriate number and zero those that follow:
MAJOR for major updates with incompatible API changesMINOR for new functionality that doesn’t affect backwards compatibilityPATCH for bug fixes
Switch to ES6 Modules
Ensure your project uses standard ES6 modules by adding "type": "module", to package.json in your editor (it can go anywhere in the root object, but is placed above "main" here):
{
"name": "express",
"version": "1.0.0",
"description": "Example Express app",
"type": "module",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Craig Buckler",
"license": "MIT"
}
ES6 modules are identical to those used in web browsers. Node.js uses CommonJS by default, but ES6 support arrived in version 13. ES6 modules will become predominant over time, so we’ll use ES6 throughout this course.
Node can import CommonJS modules using ES6 syntax. It will also make suggestions if there’s a potential issue or conflict. However, you may encounter problems with some modules written in CommonJS syntax, especially if they haven’t been updated for a few years.
Install Express
Install Express from your project directory using npm:
npm install express
After completion, your package.json file will have a new "dependencies" object, which lists the modules required when your project runs. It contains a reference to "express" and its latest version number (the leading ^ means Express can upgrade to a compatible version such as 4.17.2 or 4.18.0 but not 5.0.0):
{
"name": "express",
"version": "1.0.0",
"description": "Example Express app",
"type": "module",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Craig Buckler",
"license": "MIT",
"dependencies": {
"express": "^4.17.1"
}
}
You’ll also find the following:
- a new
package-lock.json file for npm internal use, which lists all the installed modules
- a new
node_modules folder, which contains the Express module and all submodules code (around 2MB of files)
Runtime Dependencies and Development Dependencies
A module such as Express is required for your application to run. It’s a dependency.
You can also install development dependencies, which are typically build tools that are only required on your development PC. Examples include JavaScript bundlers such as Rollup, CSS preprocessors such as Sass, and live reload systems such as Browsersync.
npm presumes a module is a runtime dependency unless you add the --save-dev switch during installation. For example:
npm install browser-sync --save-dev
This installs Browsersync, but references it in a "devDependencies" object in package.json. Running npm install on a production server where the NODE_ENV environment variable is set to production would not install Browsersync.
The distinction between a dependency and a development dependency is not always straightforward. For example, you could run Rollup on a production server to create minified JavaScript files.
Create the Express Entry Script
You can now write code that uses Express to create a web application. Add a new index.js file in the project directory with the following code:
// Express application
import express from 'express';
// configuration
const
cfg = {
port: process.env.PORT || 3000
};
// Express initiation
const app = express();
// home page route
app.get('/', (req, res) => {
res.send('Hello World!');
});
// start server
app.listen(cfg.port, () => {
console.log(`Example app listening at http://localhost:${ cfg.port }`);
});
To make starting this app a little easier, edit package.json and change the "scripts" object to this:
"scripts": {
"start": "nodemon index.js"
},
If you don’t have nodemon installed, you can install it globally with npm install nodemon -g. If you’d rather use node directly, use "node index.js" as your "start" script (but you’ll need to stop and restart your app every time you want to test a change).
Start the application with npm start and browse to http://localhost:3000.
The script imports the express module and creates an instance named app.
A single routing function is defined to handle HTTP GET requests to the root / path:
// home page route
app.get('/', (req, res) => {
res.send('Hello World!');
});
What Is Routing?
Routing determines which functions Express executes when it receives a request for a specific URL, such as / or /another/path/.
Ultimately, one function will return an HTTP response and terminate further processing. The order of your routing functions is therefore critical: a function won’t run if an earlier function completes the request.
A routing function is passed these two objects:
Try adding another routing function below the / handler to handle HTTP GET requests to /hello/:
// another route
app.get('/hello/', (req, res) => {
res.send('Hello again!');
});
Once the application has restarted, open http://localhost:3000/hello/ in your browser to see a “Hello again!” message.
No other URL routes are defined. Entering a different URL path in the browser—such as http://localhost:3000/abc—returns Cannot GET /abc. Routing is a central part of Express, and the framework provides options for parsing and responding to different URLs.
The end of the script has an app.listen() call to start the Express server listening on the defined port.
See the course code/ch05/express01 directory and associated video to run the code created so far.
Should You Switch to HTTPS?
Probably not.
All the Node.js examples in this course respond to HTTP requests on port 3000 by default:
// start server
app.listen(cfg.port, () => {
console.log(`Example app listening at http://localhost:${ cfg.port }`);
});
HTTPS requires a Secure Socket Layer (SSL) certificate. These are issued by certificate authorities for use on a specific domain to encrypt tamper-proof data between the browser and server.
For local testing, developers often create their own self-signed certificates using the command line or online tools.
If you have a private key file named server.key, and a site certificate named server.crt, an Express app can read the SSL files, create an HTTPS server, and pass the Express app object as a listener:
// start HTTPS server
import { createServer } from 'https';
import { readFileSync } from 'fs';
createServer(
{
key: fs.readFileSync('./server.key'),
cert: fs.readFileSync('./server.crt')
},
app
).listen(cfg.port);
(This replaces the HTTP app.listen() code above.)
Your application will now accept requests to https://localhost:3000/—although your browser will warn that the certificate has not been issued by a recognized Authority.
Problems with this approach include the following:
- You must manage different sets of certificates for production, staging, and every development PC.
- You still need an HTTP server to forward invalid HTTP requests to HTTPS.
- There are subtle differences when using real and self-signed certificates. For example, browsers don’t cache data from a self-signed server. Applications could run fine locally but experience cache-related issues in production.
- The Node.js app must listen on port 443 when deployed to a production server. It must be launched by a superuser (
sudo node index.js), but this grants the app permission to do anything. It could accidentally wipe all system files!
A better approach is to use a web server such as NGINX as a reverse proxy. It can handle SSL, HTTP requests, and static files, but forward all requests to the Node.js app (over HTTP) when necessary. (See chapter 18 for deployment options.)
Serve Static Files
Most web applications contain static files that return the same response to all users. These could include images, favicons, CSS stylesheets, client-side JavaScript, pre-rendered HTML pages, or any other asset.
It would be painful to programmatically assign routes for every file. Express allows you to define a single directory that contains static assets and returns any file that matches the URL path.
Create a directory named static in your project folder and add a file named page.html with the following content:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Static page</title>
<meta name="viewport" content="width=device-width,initial-scale=1" />
</head>
<body>
<h1>This is a static page</h1>
</body>
</html>
Edit your index.js file and add the following code after the final app.get() route:
// serve static assets
app.use(express.static( 'static' ));
(The following “Express Middleware Functions” section explains this code.)
Save and restart the application, then open http://localhost:3000/page.html in your browser.
Try adding pages, images, or other assets to the static directory or a subdirectory within it. For example, an image at /static/images/myimage.png can be viewed in the browser at http://localhost:3000/images/myimage.png.
Efficient Static Assets
In this example, Express only checks the file system for a matching static asset when it can’t be handled by a routing function. However, you could check for assets first if your application mostly consists of static files.
On production servers, it’s more efficient to use a frontend web server such as NGINX to serve static assets and bypass Node.js processing entirely.
Express Middleware Functions
The app.use() method used above to define the static directory introduces the concept of Express middleware. Middleware functions run in the sequence defined in the code, and can typically:
- run code on every request
- manipulate or change the request and response objects
- terminate a response—perhaps if the user isn’t logged in
- call the next middleware function
In this case, express.static( 'static' ) returns a middleware function that handles static directory processing.
All middleware functions receive three arguments:
The following middleware function logs every URL request to the terminal:
// log every request to the terminal
app.use((req, res, next) => {
console.log(req.url);
next();
});
You should place this function before any others that could end processing. No logging would occur if you placed it after URL routing or static asset middleware that succeeded in returning a response.
Define Working Directories
A hard-coded static directory is used above. That’s fine for Express, but what if another module needed to locate the same directory to read or write a file?
We can define a fully qualified reference to all working directories in the cfg configuration object. This used to be easy in CommonJS (see Chapter 8 for more on this topic) because Node provided a __dirname constant with the full directory of the current module. The situation is more complex in ES6 modules, because they’re referenced by URL—not by file. The URL of the current module is available in import.meta.url, so it can be parsed to a file path using the standard Node.js library:
import { fileURLToPath } from 'url';
import { dirname, sep } from 'path';
const __dirname = dirname(fileURLToPath( import.meta.url )) + sep;
The url module provides a fileURLtoPath() function, which converts a file:// URL to a fully qualified file path.
The path module provides a dirname() function to extract the directory from a path and a sep constant with the platform-specific path separator (/ on POSIX, \ on Windows).
Update the top of index.js accordingly:
// Express application
import express from 'express';
import { fileURLToPath } from 'url';
import { dirname, sep } from 'path';
// configuration
const
__dirname = dirname(fileURLToPath( import.meta.url )) + sep,
cfg = {
port: process.env.PORT || 3000,
dir: {
root: __dirname,
static: __dirname + 'static' + sep
}
};
console.dir(cfg, { depth: null, color: true });
// Express initiation
// ...rest of code
Then change the reference to the hard-coded static directory:
// serve static assets
app.use(express.static( cfg.dir.static ));
The application shows the configuration settings when starting, but the static page at http://localhost:3000/page.html should work as before.
Other modules can’t access the cfg object unless you export it. The active app object can also be useful, so add the following code at the end of index.js:
// export defaults
export { cfg, app };
Compressing HTTP Responses
To improve web application performance, you should compress assets before they’re returned to the browser over the network. The compression middleware module can handle this for you. Stop your app, then install the module:
npm install compression
The dependencies section of your package.json file updates accordingly:
"dependencies": {
"compression": "^1.7.4",
"express": "^4.17.1"
}
Load the module at the top of index.js:
// Express application
import express from 'express';
import compression from 'compression';
Then add it as one of the first middleware functions (before routers and static file handlers):
// HTTP compression
app.use( compression() );
It won’t make a noticeable difference to performance here, but addressing performance at the start of a project puts you one step ahead of most teams!
Disable Express Identification
By default, Express sets the following HTTP response header:
X-Powered-By: Express
It doesn’t do any harm, but you can disable it with app.disable() in index.js:
// Express initiation
const app = express();
// do not identify Express
app.disable('x-powered-by');
It will save a few bytes on every HTTP request, and will also give malicious hackers less information about your Node.js technology stack.
Handle 404 Not Found Errors
Add the following code as the last middleware function to gracefully handle errors when a page or asset can’t be found:
// 404 error
app.use((req, res) => {
res.status(404).send('Not found');
});
This returns a “Not Found” message with a 404 HTTP header code, but you could also do one of the following options:
- redirect to an appropriate page
- show suggested pages to the user
- log bad requests to a file for further analysis
See the course code/ch05/express02 directory and associated video to run the code created so far.
Add an HTML Template Engine
Node.js has a wide range of HTML template engines that create HTML pages or snippets for output. A typical engine will take an HTML template and:
- substitute variables with actual values
- allow the inclusion of partials such as headers, footers, menus, and so on
- permit basic programming functionality, such as conditions and loops
Template Performance
Ideally, your HTML templates should do as little as possible at runtime. You may be able to pre-render some parts of a template, such as including other files (partials) so your app has less work to do when rendering a page.
Popular templating options include Pug, Nunjucks, and EJS, which we’ll use here, because it’s one of the simplest, fastest, and most popular options. Many HTML template engines work with Express, but most provide instructions in situations where there’s no direct support.
In this example, you’ll create a simple message.ejs template that’s used to display single messages such as “Hello World!” in an <h1> tag. Stop your server and install EJS with npm install ejs.
The dependencies section of your package.json file updates accordingly:
"dependencies": {
"compression": "^1.7.4",
"ejs": "^3.1.6",
"express": "^4.17.1"
}
Now create a views subdirectory in your project. Add a file to it named message.ejs with the code to output a title variable:
<%- include('partials/_htmlhead'); -%>
<h1><%= title %></h1>
<%- include('partials/_htmlfoot'); -%>
This template includes other partials, so create a partials subdirectory in views with a _htmlhead.ejs file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title><%= title %></title>
<meta name="viewport" content="width=device-width,initial-scale=1" />
</head>
<body>
Also create an _htmlfoot.ejs file:
</body>
</html>
Open the Express entry index.js file and add a new cfg.dir.views property that points at the views directory:
// configuration
const
__dirname = dirname(fileURLToPath( import.meta.url )) + sep,
cfg = {
port: process.env.PORT || 3000,
dir: {
root: __dirname,
static: __dirname + 'static' + sep,
views: __dirname + 'views' + sep
}
};
Add this code before any routes and middleware:
// use EJS templates
app.set('view engine', 'ejs');
app.set('views', cfg.dir.views);
This sets EJS as the Express view engine with files contained in the views directory.
EJS is invoked using the Express Response render() method in a routing function. Update the functions /, /hello/, and the 404 handler:
// home page route
app.get('/', (req, res) => {
res.render('message', { title: 'Hello World!' });
});
// another route
app.get('/hello/', (req, res) => {
res.render('message', { title: 'Hello again!' });
});
// serve static assets
app.use(express.static( cfg.dir.static ));
// 404 errors
app.use((req, res) => {
res.status(404).render('message', { title: 'Not found' });
});
The render method is passed the name of the template ('message'—the .ejs extension can be omitted) and an object containing name/value pairs. A title is set in this example.
Start your Express server with npm start, then open http://localhost:3000/ in a browser.
The result may not be significantly different, but it’s a fully rendered HTML page with an <h1> title. (View the source, Luke.)
Advanced Routing
URL routing is at the heart of Express processing. You’ve developed simple routes that run functions for specific matching URLs, but there are more options:
Routing Path Expressions
Simple URL routes are defined in the examples above. For example:
// another route
app.get('/hello/', (req, res) => {
res.send('Hello again!');
});
The route handles HTTP GET requests to /hello/, although Express will do the following:
- Ignore casing. The paths
/Hello/ and /HELLO/ will match the /hello/ route unless you add app.set('case sensitive routing', true) to index.js.
- Ignore closing slashes. The paths
/hello/ and /hello match the same route unless you add app.set('strict routing', true) to index.js.
As well as exact routes, you can define regular expression patterns to match a range of URLs. For example:
? denotes that the preceding character is optional. A route of /ab?cd/ matches the URL paths /abcd/ and /acd/.+ denotes that the preceding character must appear one or more times. A route of /ab+cd/ matches the URL paths /abcd/, /abbcd/, /abbbbbcd/ and so on.* denotes any number of characters. A route of /ab*cd/ matches the URL paths /abcd/, /ab123cd/, /ab-node.js-cd/ and so on.- A more complex route of
/.+Script$/ matches the URL paths /JavaScript/ and /ECMAScipt/, but not /Scripting/.
Express uses the Path-to-RegExp module to parse paths. The Express Route Tester tool can help you build and debug more complex URLs.
Routing Path Parameters
Route parameters are named path segments preceded by a colon (:) to identify a variable in the URL. For example, the route /user/:id matches any URL path starting /user/ that has a single segment—such as /user/123 or /user/abc.
Captured values are available in the Request params object, so req.params.id would be set to 123 or abc in the examples above.
Any number of URL parameters can be defined. The following route function would run for the path /author/Craig-Buckler/book/Node.js:
// return a value for a user
app.get('/author/:name/book/:bookName', (req, res, next) => {
console.log(`author: ${ req.params.name }`); // "Craig-Buckler"
console.log(` book: ${ req.params.bookName }`); // "Node.js"
next();
});
HTTP Route Methods
The examples above handle HTTP GET requests by defining an app.get() function. Express supports all the other HTTP methods, including:
- HTTP POST with
app.post()
- HTTP PUT with
app.put()
- HTTP DELETE with
app.delete()
app.all() handles all HTTP methods to a specific route. The function can examine the req.method property to determine which HTTP method was used.
Creating a Route Handler
Defining all route handler functions in the entry index.js script becomes impractical as your application grows in complexity. A better option is to create route handling middleware in separate files with related functionality.
The following example updates the Express code so that requests to any URL starting /hello/ are handled in a single router file. Two GET requests are implemented:
/hello/:name returns a page saying hello to someone by name. For example, /hello/craig displays “Hello Craig!”/hello/:lang/:name returns a page saying hello to someone by name in a specific language. For example, /hello/fr/craig switches to French and displays “Bonjour Craig!”
Before doing this, create a lib subdirectory in your project folder for generic library modules. Add a new file at lib/locale.js with the following code:
// localisation
// international greetings
export const hello = {
au: 'G\'day',
cn: 'Nǐ hǎo',
en: 'Hello',
de: 'Hallo',
es: 'Hola',
fr: 'Bonjour',
jp: 'Kon\'nichiwa'
};
Then add lib/string.js with the following code:
// string functions
// capitalize the first letter of all words
export function capitalize(str) {
return str
.trim()
.toLowerCase()
.split(' ')
.map(word => word.charAt(0).toUpperCase() + word.slice(1))
.join(' ');
}
Next, create a new routes subdirectory in your project folder for routing middleware. Add a new file at routes/hello.js with code to define the two routing functions:
// /hello/ route
import { Router } from 'express';
import { hello } from '../lib/locale.js';
import { capitalize } from '../lib/string.js';
export const helloRouter = Router();
// say hello in English
helloRouter.get('/:name', (req, res, next) => {
res.render(
'message',
{ title: `${ hello.en } ${ capitalize( req.params.name ) }!` }
);
});
// say hello in a specific language
helloRouter.get('/:lang/:name', (req, res, next) => {
res.render(
'message',
{ title: `${ hello[req.params.lang] || hello.en } ${ capitalize( req.params.
➥name ) }!` }
);
});
This defines an Express Router object named helloRouter. Routers are mini applications that can perform routing and middleware functions.
The first route defines a function for the parametrized path /:name. (You should not specify the full /hello/:name route, because this router file will become the handler for all /hello/ paths.) The function renders the message template with a title that says “Hello” (in English) to the :name value passed on the URL (req.params.name).
The second route defines a function for the parametrized path /:lang/:name. Again, this renders the message template with a title that uses a localized version of “Hello” as defined in lib/locale.js.
To use your Router file, open index.js then remove these lines:
// another route
app.get('/hello/', (req, res) => {
res.send('Hello again!');
});
Replace them with this code:
// /hello/ route
import { helloRouter } from './routes/hello.js';
app.use('/hello', helloRouter);
app.use() defines the helloRouter middleware rather than a single app.get() route.
If necessary, restart your Express app with npm start and open a URL in your browser, such as http://localhost:3000/hello/craig to see “Hello Craig!”
Switch to an Australian greeting with the URL http://localhost:3000/hello/au/craig.
See the course code/ch05/express02 directory and associated video to run the code created so far.
Exercises
Attempt the following updates to improve your Express coding experience:
- Improve the
message template to add a stylesheet. (Hint: the CSS could be a static file.)
- Create and use a new template that also outputs the current URL to the page. (Hint: the Express Request object passed as
req can help.)
- Create a new router to say “Goodbye” in a similar way to the “Hello” example.
Summary
This chapter introduced the Express framework for server-side web applications. Other Node.js server frameworks follow similar conventions and some are compatible with Express middleware.
This is just the start of the possibilities. In the following chapters, we’ll look at ways to process form data, implement REST APIs, and manipulate databases in your Express applications.
Quiz
1. Express is:
- a. similar to Apache or NGINX but programmable with Node.js code
- b. a Node.js server-side application framework
- c. one of several Node.js web server frameworks
- d. all of the above
2. Express is typically installed in a project as:
- a. a global module
- b. a development dependency
- c. a dependency
- d. a single static JavaScript file
3. A package.json file is used to:
- a. store configuration information about a Node.js application
- b. store application runtime data
- c. configure npm
- d. all of the above
4. An Express middleware function:
- a. is an internal Express module
- b. runs when an Express app starts
- c. can handle or manipulate the HTTP request and response
- d. runs when an Express app shuts down
5. Middleware functions are passed the following parameters in order:
- a. the
next function, the Request object, the Response object
- b. the Request object, the Response object, the
next function
- c. the
next function, the Response object, the Request object
- d. the Response object, the Request object, the
next function
