Pulsar API

This is a boilerplate starter-kit for building a GraphQL API with NestJS, Prisma and GraphQL. The starter-kit is based on NestJS GraphQL starter.

Features

Roles and Permissions with CASL.
GraphQL playground behind authentication.
Code-First decorators and classes.
Prisma for database modelling, migration and type-safe access (Postgres, MySQL & MongoDB).
JWT authentication with passport-jwt.
REST API docs with Swagger.

Prisma Setup

1. Install Dependencies

Install Nestjs CLI to start and generate CRUD resources

# npm
npm i -g @nestjs/cli
# yarn
yarn add -g @nestjs/cli

Install the dependencies for the Nest application:

# npm
npm install
# yarn
yarn install

2. Database with Docker

MySQL

Set up a development MySQL with Docker. Copy .env.example and rename to .env - cp .env.example .env - which sets the required environments for MySQL such as MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE. Update the variables as you wish and select a strong password.

Start the MySQL database

docker-compose -f docker-compose.mysql.yml up -d
# or
npm run docker:db

PostgreSQL

Set up a development PostgreSQL with Docker. Copy .env.example and rename to .env - cp .env.example .env - which sets the required environments for PostgreSQL such as POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB. Update the variables as you wish and select a strong password.

Start the PostgreSQL database

docker-compose -f docker-compose.postgres.yml up -d

3. Prisma Migrate

Prisma Migrate is used to manage the schema and migration of the database. Prisma datasource requires an environment variable DATABASE_URL for the connection to the PostgreSQL database. Prisma reads the DATABASE_URL from the root .env file.

Use Prisma Migrate in your development environment to

Creates migration.sql file
Updates Database Schema
Generates Prisma Client

npx prisma migrate dev
# or
npm run migrate:dev

If you like to customize your migration.sql file run the following command. After making your customizations run npx prisma migrate dev to apply it.

npx prisma migrate dev --create-only
# or
npm run migrate:dev:create

If you are happy with your database changes you want to deploy those changes to your production database. Use prisma migrate deploy to apply all pending migrations, can also be used in CI/CD pipelines as it works without prompts.

npx prisma migrate deploy
# or
npm run migrate:deploy

4. Prisma Client JS

Prisma Client JS is a type-safe database client auto-generated based on the data model.

Generate Prisma Client JS by running

Note: Every time you update schema.prisma re-generate Prisma Client JS

npx prisma generate
# or
npm run prisma:generate

5. Seed the database data with this script

Execute the script with this command:

npm run seed

6. Start NestJS Server

Run Nest Server in Development mode:

npm run start

# watch mode
npm run start:dev

Run Nest Server in Production mode:

npm run start:prod

GraphQL Playground for the NestJS Server is available here: http://localhost:3000/graphql

back to top

GraphQL Playground

Open up the example GraphQL queries and copy them to the GraphQL Playground. Some queries and mutations are secured by an auth guard. You have to acquire a JWT token from signup or login. Add the accessTokenas followed to HTTP HEADERS in the playground and replace YOURTOKEN here:

{
  "Authorization": "Bearer YOUR_TOKEN"
}

Rest Api

RESTful API documentation available with Swagger.

Docker

Nest server is a Node.js application and it is easily dockerized.

See the Dockerfile on how to build a Docker image of your Nest server.

Now to build a Docker image of your own Nest server simply run:

# give your docker image a name
docker build -t <your username>/nest-prisma-server .
# for example
docker build -t nest-prisma-server .

After Docker build your docker image you are ready to start up a docker container running the nest server:

docker run -d -t -p 3000:3000 --env-file .env nest-prisma-server

Now open up localhost:3000 to verify that your nest server is running.

When you run your NestJS application in a Docker container update your .env file

- DB_HOST=localhost
# replace with name of the database container
+ DB_HOST=postgres

# Prisma database connection
+ DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DB_HOST}:${DB_PORT}/${POSTGRES_DB}?schema=${DB_SCHEMA}&sslmode=prefer

If DATABASE_URL is missing in the root .env file, which is loaded into the Docker container, the NestJS application will exit with the following error:

(node:19) UnhandledPromiseRejectionWarning: Error: error: Environment variable not found: DATABASE_URL.
  -->  schema.prisma:3
   |
 2 |   provider = "postgresql"
 3 |   url      = env("DATABASE_URL")

Docker Compose

You can also set up a database and Nest application with the docker-compose

# building new NestJS docker image
docker-compose build
# or
npm run docker:build

# start docker-compose
docker-compose up -d
# or
npm run docker

Schema Development

Update the Prisma schema prisma/schema.prisma and after that run the following two commands:

npx prisma generate
# or in watch mode
npx prisma generate --watch
# or
npm run prisma:generate
npm run prisma:generate:watch

back to top

NestJS - Api Schema

The schema.graphql is generated with code first approach from the models, resolvers and input classes.

You can use class-validator to validate your inputs and arguments.

Resolver

To implement the new query, a new resolver function needs to be added to users.resolver.ts.

@Query(returns => User)
async getUser(@Args() args): Promise<User> {
  return await this.prisma.client.user(args);
}

Restart the NestJS server and this time the Query to fetch a user should work.

back to top

Front-end

A GraphQL client is necessary to consume the GraphQL api provided by the NestJS Server.

Checkout Apollo a popular GraphQL client which offers several clients for React, Angular, Vue.js, Native iOS, Native Android and more.

React

Setup

To start using Apollo React simply run in a React project:

npm install @apollo/client graphql
# or
yarn add @apollo/client graphql

You can also add the ApolloProvider in the App component to make Apollo available in your React App.

import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'http://localhost:3000/graphql',
  cache: new InMemoryCache(),
});
  
ReactDOM.render(
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>,
  document.getElementById('root')
);

You need to set the URL to the NestJS GraphQL Api. Open the file src/app/graphql.module.ts and update uri:

const uri = 'http://localhost:3000/graphql';

To use Apollo-React you can use the useQuery and useMutation hooks.

back to top

Queries

To execute a query you can use:

const { loading, error, data } = useQuery(YOUR_QUERY);

Here is an example how to fetch your profile from the NestJS GraphQL Api:

const CurrentUserProfile = gql`
  query CurrentUserProfile {
    me {
      id
      email
      name
    }
  }
`;

function Profile() {
  const { loading, error, data } = useQuery(CurrentUserProfile);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error :(</p>;

  return (
    <div>
      <p>Me id: {data.me.id}</p>
      <p>Me email: {data.me.email}</p>
      <p>Me name: {data.me.name}</p>
    </div>
  );
}

This will end up in an GraphQL error because Me is protected by an @UseGuards(GqlAuthGuard) and requires an Bearer TOKEN.

Please refer to the Authentication section.

back to top

Mutations

To execute a mutation you can use:

const [login, { data }] = useMutation(YOUR_MUTATION);

Here is an example how to login into your profile using the login Mutation:

const Login = gql`
  mutation Login {
    login(email: "[email protected]", password: "duffbeer") {
      token
      user {
        id
        email
        name
      }
    }
  }
`;

function Signin() {
  const [login, { data }] = useMutation(Login);

  return (
    <div>
      <button
        onClick={() => {
          login();
        }}
      >
        Login
      </button>
    </div>
  );
}

back to top

Subscriptions

To execute a subscription you can use:

const { loading, error, data } = useSubscription(YOUR_SUBSCRIPTION_QUERY);

back to top

Angular

Setup

To start using Apollo Angular simply run in an Angular and Ionic project:

ng add apollo-angular

HttpLink from apollo-angular requires the HttpClient. Therefore, you need to add the HttpClientModule to the AppModule:

imports: [BrowserModule,
    HttpClientModule,
    ...,
    GraphQLModule],

You can also add the GraphQLModule in the AppModule to make Apollo available in your Angular App.

You need to set the URL to the NestJS GraphQL Api. Open the file src/app/graphql.module.ts and update uri:

const uri = 'http://localhost:3000/graphql';

To use Apollo-Angular you can inject private apollo: Apollo into the constructor of a page, component or service.

back to top

Queries

To execute a query you can use:

this.apollo.query({query: YOUR_QUERY});

# or

this.apollo.watchQuery({
  query: YOUR_QUERY
}).valueChanges;

Here is an example how to fetch your profile from the NestJS GraphQL Api:

const CurrentUserProfile = gql`
  query CurrentUserProfile {
    me {
      id
      email
      name
    }
  }
`;

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
})
export class HomePage implements OnInit {
  data: Observable<any>;

  constructor(private apollo: Apollo) {}

  ngOnInit() {
    this.data = this.apollo.watchQuery({
      query: CurrentUserProfile,
    }).valueChanges;
  }
}

Use the AsyncPipe and SelectPipe to unwrap the data Observable in the template:

<div *ngIf="data | async | select: 'me' as me">
  <p>Me id: {{me.id}}</p>
  <p>Me email: {{me.email}}</p>
  <p>Me name: {{me.name}}</p>
</div>

Or unwrap the data using RxJs.

This will end up in an GraphQL error because Me is protected by an @UseGuards(GqlAuthGuard) and requires an Bearer TOKEN. Please refer to the Authentication section.

back to top

Mutations

To execute a mutation you can use:

this.apollo.mutate({
  mutation: YOUR_MUTATION,
});

Here is an example how to login into your profile using the login Mutation:

const Login = gql`
  mutation Login {
    login(email: "[email protected]", password: "pizzaHawaii") {
      token
      user {
        id
        email
        name
      }
    }
  }
`;

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
})
export class HomePage implements OnInit {
  data: Observable<any>;

  constructor(private apollo: Apollo) {}

  ngOnInit() {
    this.data = this.apollo.mutate({
      mutation: Login,
    });
  }
}

back to top

Subscriptions

To execute a subscription you can use:

this.apollo.subscribe({
  query: YOUR_SUBSCRIPTION_QUERY,
});

back to top

Authentication

To authenticate your requests you have to add your TOKEN you receive on signup and login mutation to each request which is protected by the @UseGuards(GqlAuthGuard).

Because the apollo client is using HttpClient under the hood you are able to simply use an Interceptor to add your token to the requests.

Create the following class:

import { Injectable } from '@angular/core';
import {
  HttpEvent,
  HttpInterceptor,
  HttpHandler,
  HttpRequest,
} from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable()
export class TokenInterceptor implements HttpInterceptor {
  constructor() {}

  intercept(
    req: HttpRequest<any>,
    next: HttpHandler
  ): Observable<HttpEvent<any>> {
    const token = 'YOUR_TOKEN'; // get from local storage
    if (token !== undefined) {
      req = req.clone({
        setHeaders: {
          Authorization: `Bearer ${token}`,
        },
      });
    }

    return next.handle(req);
  }
}

Add the Interceptor to the AppModule providers like this:

providers: [
    ...
    { provide: HTTP_INTERCEPTORS, useClass: TokenInterceptor, multi: true },
    ...
  ]

After you configured the Interceptor and retrieved the TOKEN from storage your request will succeed on resolvers with @UseGuards(GqlAuthGuard).

back to top

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
graphql		graphql
prisma		prisma
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.node-version		.node-version
.prettierrc.json		.prettierrc.json
Dockerfile		Dockerfile
Dockerfile.alpine		Dockerfile.alpine
LICENSE		LICENSE
README.md		README.md
docker-compose.migrate.yml		docker-compose.migrate.yml
docker-compose.mysql.yml		docker-compose.mysql.yml
docker-compose.postgres.yml		docker-compose.postgres.yml
docker-compose.yml		docker-compose.yml
graphql.config.yml		graphql.config.yml
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
run.sh		run.sh
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Pulsar API

Features

Overview

Prisma Setup

1. Install Dependencies

2. Database with Docker

MySQL

PostgreSQL

3. Prisma Migrate

4. Prisma Client JS

5. Seed the database data with this script

6. Start NestJS Server

GraphQL Playground

Rest Api

Docker

Docker Compose

Schema Development

NestJS - Api Schema

Resolver

Front-end

React

Setup

Queries

Mutations

Subscriptions

Angular

Setup

Queries

Mutations

Subscriptions

Authentication

About

Releases

Packages

Languages

License

jstnmthw/pulsar-api

Folders and files

Latest commit

History

Repository files navigation

Pulsar API

Features

Overview

Prisma Setup

1. Install Dependencies

2. Database with Docker

MySQL

PostgreSQL

3. Prisma Migrate

4. Prisma Client JS

5. Seed the database data with this script

6. Start NestJS Server

GraphQL Playground

Rest Api

Docker

Docker Compose

Schema Development

NestJS - Api Schema

Resolver

Front-end

React

Setup

Queries

Mutations

Subscriptions

Angular

Setup

Queries

Mutations

Subscriptions

Authentication

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages