Nest.js Example: Caster API

This is an example app for the Nest.js Video Series by Brandon Konkle. It implements a basic API to support a number of hypothetical frontends for the imaginary "Caster" app, a tool to help podcasters, broadcasters, and streamers coordinate show content with their co-hosts and guests. Limited to just the API to support the front end.

API Features

• Create and log into a user account, and save a personal profile.
• Create a show with episodes.
• Create topics to discuss within an episode.
• Present a live interface highlighting topics and allowing participants to chat.

Libraries & Tools

• TypeScript
• GraphQL
• Nest.js
• Prisma
• Socket.io
• ioredis
• Nx
• Casl
• Yarn

Local Development

After checking out the repository, install dependencies with Yarn:

yarn

Then, follow the example in .env.example to create your own apps/api/.env file.

Authentication Setup

Authentication uses a standard OAuth2 JWKS setup that relies on an external identity server to issue and validate tokens. To start off you'll need an OAuth2 endpoint, something like https://my-app.us.auth0.com (if you're using Auth0) or https://mydomain.auth.us-east-1.amazoncognito.com (if you're using AWS Cognito). Set this as the OAUTH2_URL variable in your apps/api/.env.

Then, set the OAUTH2_AUDIENCE to localhost, or whatever your authentication provider prefers.

Authenticated Integration Tests

For thorough integration testing, a special "test automation" OAuth2 client is used. In some cases this may be a separate client configured through your authentication provider, one that is configured to allow login via the password grant flow using the client id and client secret. In other cases this may be the same as your main client, with settings changed to enable the password grant flow.

Either way, this should not be enabled in your Production environment. The password grant flow should only be used for testing. In Production, your client applications will most likely use the authorization code flow (with a PKCE challenge required for native applications that can't safely store a client secret, and recommended even for applications that can).

Set the client id and secret to OAUTH2_CLIENT_ID and OAUTH2_CLIENT_SECRET in your apps/api/.env.

Finally, create two test users to use with the integration tests. Save their credentials to TEST_USER, TEST_PASS, TEST_ALT_USER, and TEST_ALT_PASS. These credentials should not be valid in Production.

DB Setup

Use docker-compose to launch a local Postgres database (and a Redis server) by running:

nx docker-up

Then, run migrations to catch your schema up to the latest:

nx db-migrate

The first time you do this on a fresh database, you should see:

PostgreSQL database caster created at localhost:1701

And finally:

Your database is now in sync with your schema.

Running the Local Server

Use nx to run the server locally:

nx serve

Running Unit Tests

To test a library with nx:

nx test users

To test an individual suite within a library:

nx test users --testFile users.resolver

To test all of the libraries (and apps) together:

yarn test

Running Integration Tests

To integration test, you need to have the Docker Compose stack with Postgres and Redis running locally, or within your CI pipeline.

NOTE: This is destructive, and will wipe out data within your local database. See below for how to use an alternate test database locally.

To run a single integration suite:

nx integration --testFile events

To run all of the integration tests together:

yarn integration

Using an Alternate Test Database

Running integration tests is destructive. If you want to preserve your local data, use an alternate database for local integration testing. Create an apps/api/.env.test file and customize the DATABASE_URL:

DATABASE_URL=postgresql://caster:caster@localhost:1701/caster_test

Then run the command to reset the test database:

yarn db:reset:test