home

Clone the repo

The first step is to clone this repository locally. From the OS prompt

git clone https://github.com/nestjsplus/nest-cats

Doing so will create a folder called nest-cats. The repository will have a bunch of branches as described below.

Then, just run npm install to set up NestJS and other tools needed to start coding.

cd nest-cats npm install

Using the repo

You can check out a branch corresponding to the starting or ending state of the code presented in each chapter of the official NestJS docs.

You can run the code as it exists at any of these states by sending inbound HTTP requests (I recommend using HTTPie as described below; I 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 "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 official NestJS docs don't perfectly fit together into a whole (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.

Because of the above, if you want to follow along and "live code" with the official docs, you'll need to do a tiny bit of coordination back and forth. To do that, follow the general guidelines in Using Nest Cats below.

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

How the repo is organized

Each chapter of the docs has a corresponding pair of branches in the repository*:

• one that represents the nest-cats app as of the beginning of the chapter. This branch is called <chapter-name>-start, where <chapter-name> is the (lower-cased) exact name of the chapter in the documentation table of contents. For example, the chapter Controllers has a branch called controllers-start.
• one that represents the nest-cats app with all code implemented as of the end of the chapter. This branch is called <chapter-name>-end. For example, the chapter Controllers has a branch called controllers-end.

*There are a couple of exceptions:

1. First steps has only one branch, as there's no prior starting state.
2. Some chapters have an additional branch, labeled <chapter-name>-appendix, which includes additional code examples from the docs chapter that are what I call "mini branches" off the main nest-cats codeline; e.g., code samples in the docs chapter that exist for explaining some concept, but can't neatly be included in the main app.
3. There are a few additional branches that do not correspond to any chapter, but which add some optional features useful for knitting together a helpful app, or exploring some concept in further detail.

Using nest-cats

There are 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. If taking this approach, follow the guide page on this wiki for the chapter (e.g., Providers) as you read the docs chapter and add code. The guide (wiki) page helps you keep this code base synchronized with the code snippets in the docs chapter.
      2. Alternatively, 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 on that guide page.
   3. In some cases, there are small code "branches" in the docs that don't fit into "the nest 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 NestJS 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 you 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 with the http command hanging (this stackoverflow article describes the issue, 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.

Go to First Steps now.