Template for a Prisma, Pothos & GraphQL Server

Type‑safe, stable, scalable.

This is a template for a Node.js GraphQL server using Prisma and Pothos including basic authentication. It is designed as a starting point for building a GraphQL server with stability and scalability in mind. It features end-to-end type safety from the database, through GraphQL and all the way to the client. It is recommended to use Relay as the client for servers built using this template.

Technologies

Prisma as the ORM, with the new ESM multi-file generated client.
Pothos as the GraphQL schema builder.
prisma-json-types-generator for type-safe JSON types from the database all the way to the client.
graphql-yoga
Express.js
Passport.js for Authentication
pnpm

Setup

You'll need Node.js 23+ and pnpm 10+ to use this template.

Start here: Create a new app using this template.
Run pnpm install.
Set up a Postgres database locally and add the connection string to .env as DATABASE_URL.
pnpm prisma migrate dev to create the database and run the migrations.
Run pnpm dev to start the server.
Open http://localhost:9000/graphql in your browser to see the GraphiQL, a GraphQL playground.
Open the Dev Tools and paste this code into the console to authenticate:

await (
  await fetch('/user/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'admin@nakazawa.dev',
      password: 'not-a-secure-password',
    }),
  })
).json();
// This should return a {success: true, user: …} response.

Now you are ready to execute GraphQL queries. This template comes with a viewer root query that returns the currently authenticated user. Try this query:

{
  viewer {
    id
    username
    caughtPokemon {
      edges {
        node {
          pokemon {
            id
            name
            primaryType
          }
          shiny
        }
      }
    }
  }
}

Type-safety from the database to the client

Prisma, Pothos and GraphQL allow creating type-safe APIs with minimal effort that are only loosely coupled to the client. This means that the server and client can be developed and deployed independently, which is especially advantageous when building mobile apps published on app stores. Everything flows from the database to the client, let's look at an example:

First, we define our Prisma schema, for example the User model:

model User {
  id            String          @unique @default(uuid(7))
  access        Role            @default(User)
  created       DateTime        @default(now())
  displayName   String
  email         String          @unique
  locale        String          @default("en_US")
  password      String
  salt          String
  suspended     Boolean         @default(false)
  username      String          @unique
  CaughtPokemon CaughtPokemon[]

  @@index([id(sort: Asc)])
}

Then we use Pothos to define which fields we want to expose to clients via GraphQL on a User node:

builder.prismaNode('User', {
  fields: (t) => ({
    access: t.field({
      directives: { self: {} },
      resolve: ({ access }) => access,
      type: RoleEnum,
    }),
    caughtPokemon: t.relatedConnection('CaughtPokemon', {
      cursor: 'id',
      nullable: false,
      query: {
        orderBy: { caughtAt: 'asc' },
      },
    }),
    displayName: t.exposeString('displayName', { nullable: false }),
    email: t.string({
      directives: { self: {} },
      resolve: ({ email }) => email,
    }),
    locale: t.string({
      directives: { self: {} },
      resolve: ({ locale }) => locale,
    }),
    username: t.exposeString('username', { nullable: false }),
  }),
  id: { field: 'id' },
});

To make nodes available at the top level, we need to add a query. For example a query to look up a user by username might look like this:

builder.queryFields((t) => ({
  user: t.prismaField({
    args: { username: t.arg.string({ required: true }) },
    directives: {
      requiresAuth: { role: 'User' },
    },
    resolve: (query, _, { username }) =>
      prisma.user.findUnique({
        ...query,
        where: {
          username,
        },
      }),
    type: 'User',
  }),
});

As you can see, it's minimal and highly descriptive. Through the strong typing guarantees from Prisma and Pothos, it's impossible to make mistakes. Any typos or incorrect code will be  highlighted to you by TypeScript.

The above code generates the following GraphQL schema automatically:

type User implements Node {
  access: Role @self
  caughtPokemon(
    after: String
    before: String
    first: Int
    last: Int
  ): UserCaughtPokemonConnection!
  displayName: String!
  email: String @self
  id: ID!
  locale: String @self
  username: String!
}

The default setup in this template also adds various types like connections to work with Relay.

That's it. You can now query the User type in your GraphQL API either by calling user(username: "admin") to retrieve all Pokémon caught by the user.

Developing a Node.js Server

When you make a change to a file in src/, the server restarts instantly. Every file in this template is designed to be modified by you. It's just a starting point to make you go faster.

Code Organization

Prisma code should be in src/prisma/.
GraphQL & Pothos code goes into src/graphql/.
Authentication related code goes into src/user/.

Adding GraphQL Types and Mutations

Pothos Nodes are expected to be added in src/graphql/nodes and Mutations in src/graphql/mutations. When you add a new file, run pnpm generate-graphql to automatically pull them into your GraphQL schema.

GraphQL Directives

This template supports two directives to control the visibility of fields in the GraphQL schema:

@self on the field level to make the field visible only to the currently authenticated user (viewer).
@requiresAuth(role: "User") or @requiresAuth(role: "Admin") on the object or field level to make the field visible only to users with the specified role. The role is a string that can be anything you want. You can add your own roles in the Prisma schema and use them here.

JSON Types in the Database

This template uses prisma-json-types-generator to allow typing JSON fields in the database. For example, the stats field in the CaughtPokemon model in the Prisma schema is annotated like this:

model CaughtPokemon {
  id        String   @id @default(uuid(7))
  […]

  shiny     Boolean
  /// [PokemonStats]
  stats     Json

  […]
}

And the PokemonStats type is defined in TypeScript like this:

type PokemonStats = Readonly<{
  attack: number;
  defense: number;
  hp: number;
  level: number;
  specialAttack: number;
  specialDefense: number;
  speed: number;
}>;

Running pnpm prisma generate connects the annoation with the type definition so that the stats field on CaughtPokemon is now typed as as PokemonStats when fetching or mutating database entries. For example, when you insert a new CaughtPokemon into the database, TypeScript will ensure you are providing all the correct fields:

await prisma.caughtPokemon.create({
  data: {
    …
    stats: {
      // TypeScript Error: There is a typo in `attack` and `defense` is missing altogether!
      atttack: random(70, 110),
      hp: random(60, 120),
      level: random(1, 100),
      specialAttack: random(70, 110),
      specialDefense: random(60, 100),
      speed: random(70, 100),
    },
  },
});

Note: There is no validation and no actual guarantee that the data from the database actually conforms to your defined types. This is fine and safe if your server is the only client mutating data in your database. If you have other clients mutating data in your database that might not make use of the same types, you have to actually validate the data you retrieve from your database during runtime.

Authentication

Authentication is handled using passport. This template uses the local strategy and stores users in the database. You can add other strategies like google, github, etc. by following the passport documentation.

You need to build your own authentication flow in your client that authenticates against the non-GraphQL endpoints like /user/login, /user/logout, and /user/register. See installAuthMiddleware.tsx. Check out the src/user/ folder where you can change all authentication related code based on your requirements.

Security

The sample data in this repository is insecure demo data. Before deploying a server built using this template, make sure to at least change the passwords for the seed users and the authentication secret in the .env file.

Building a client

This template is designed to be used with Relay as the client. Relay is a mature choice for a GraphQL client for TypeScript apps. The CORS policy expects the client to run at http://localhost:3000 during development. If you are using a different port, change the DEVELOPMENT_DOMAIN in .env.

Why does this template use `.tsx` as a file extension?

You can use .ts if you prefer! This template uses .tsx because it is commonly used in monorepos alongside React projects. You might also choose to use JSX in your server code. Whenever you start out using a .ts file and decide to use JSX, you have to rename the file. Blaming the file history then becomes cumbersome. It's also confusing to use two different extensions for TypeScript and the legacy casting syntax supported by .ts is not useful. There is no upside to using .ts as an extension

Why does this template use Express.js?

Express.js is still the most widely used and best supported framework in the Node.js ecosystem. It is extremely stable, and has the largest ecosystem built around it. There are many modern HTTP server frameworks, and if you like one of them, feel free to swap out Express.js (and send a Pull Request!).

License

mhaidarhanif/prisma-graphql-server-template

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages