introduction

Introduction

This repository is designed as a companion for the official NestJS docs.

TLDR;

While there's a coherent theme to the docs, the chapters don't exactly line up and build on each other in a way you can execute the features introduced in each one.*

With this repo, you can check out a branch corresponding to the starting or ending state of the code presented in each chapter. You can run the code (I recommend using HTTPie, and provide request snippets you can use with it, but you can use whatever client side request tool you want). It's fast and cheap to clone the repo. You can modify the code. You can use it as a sort of "canonical" example of recommended code; a testbed to debug your code in isolation, if you will. You can throw it away and start over again next time you need a little working laboratory.

Because the pieces of code from the docs don't perfectly fit together (as they would, for example, in and end-to-end tutorial), I've taken a little poetic license to make that so. But the end result is a project faithful to the main code examples in the docs that runs at each stage of development.

One other benefit of this repo is that it demonstrates a project organization (folders, file-naming conventions) recommended by the NestJS core team.

*This is not a criticism. There's good reason for this, as the docs currently serve as both an intro tutorial and an on-going reference for more experienced developers.

How to use it

I see two main use cases:

1. Case 1: you want to follow along with the docs and have a live environment to test the code you're learning. To do this,
   1. Do one of the following:
      1. If you want to "live code" along with the chapter, check out the branch corresponding to the start of the chapter you're reading (e.g., providers-start) and make the changes shown in the chapter. I call this follow along mode; each chapter has a guide that helps you use this code base to follow along with the chapter. Alternatively,
      2. If you just want to see a running example, check out the branch corresponding to the end of the chapter (e.g., providers-end) and test with that.
   2. In most cases, there are a few useful REST requests to make to exercise the chapter's main features, and I provide those as HTTPie requests.
   3. In some cases, there are small code "branches" in the docs that don't fit into "the cats project main line" code, but illustrate some related point. I sometimes provide more code variants corresponding to these sidelights in a special branch for the chapter, such as middleware-end-appendix.
2. Case 2: you want to experiment, or debug some bit of code, in a "known good" environment. While this repository isn't officially supported by the Nest core team, it does rely heavily on code provided by core team members. If something doesn't work as expected here, there's a good chance the problem is in Nest or in this repo's core code, and not your own. In either case, this should help diagnose an issue using simple, well-understood, common code as a platform.

Exercising the app's API

The nest-cats project is basically a RESTful API Server. Testing it requires us to fire HTTP requests at the app as it listens on some HTTP port. We need a good way to run these requests, and to document them in this guide.

HTTPie Queries

I use HTTPie as a convenient way to exercise the API. It has a pretty intuitive way of issuing HTTP requests from the command line. For example, to hit the endpoint GET /cats on localhost:3000, you type the following at your OS command prompt: http get :3000/cats

Another benefit of HTTPie is that it's easy to share requests, since they're just plain text (unlike, say, Postman). Follow the instructions at the HTTPie site to install it. Note that if you are using a Git Bash terminal window on Windows 10, you may run into this issue; this stackoverflow article describes it along with a solution.

Postman

I also sometimes use Postman, which works well for this task and has a (relatively) friendly UI. Unfortunately, it's not easy to share queries with Postman unless you sign up for the premium service. You can of course create the HTTPie queries in this guide using Postman with a little bit of cut/paste and editing effort. Indeed, I recommend Postman when we get to the Authentication chapter, as it is in fact the easiest way I've found to send Bearer tokens.

What's next

To get started, go to the First steps chapter of the docs, and the corresponding First steps chapter of this guide.