prisma-json-types-generator

The generator supports two ways to define types for Prisma fields:

1. Namespace-based Types (/// [TypeName])

Use this for reusable or complex shapes, large JSON payloads, or types that will be validated with libraries like Zod. This requires defining the type within a PrismaJson namespace in a TypeScript declaration file.

Prisma Schema:

model User {
  /// [UserProfile]
  profile Json
}

TypeScript Declaration:

import type { UserProfile as DomainUserProfile } from './domain/user-profile';

declare global {
  namespace PrismaJson {
    type UserProfile = DomainUserProfile;
  }
}

2. Inline Types (/// ![TypeExpression])

Use this for shorter, simpler types or literal unions. The full TypeScript type expression is written directly in the comment.

Prisma Schema:

model Post {
  /// !['draft' | 'published' | 'archived']
  status String

  /// ![1 | 2 | 3]
  rank Int

  /// ![{ theme: 'dark' | 'light'; twitterHandle?: string }]
  profile Json
}

The generator supports two distinct typing methods:

1. Namespace-based (/// [TypeName]): References a type defined within the PrismaJson global namespace. This is best for complex, reusable types.
2. Inline (/// ![Type]): Defines the type directly in the schema comment. This is best for simple, one-off types like enums or basic objects.

Supported Types

• Json fields: Use /// [TypeName] or /// ![Type].
• String fields (Enums): Use /// ![union_type] to create string enums.
• Numeric scalars: Use /// ![1 | 2 | 3] for Int or Float fields.
• Arrays: For array fields, keep the Prisma field as an array (e.g., tags Json[]) and use the element shape in the comment (e.g., /// [Tag]).

model Product {
  id Int @id

  // Namespace-based type
  /// [ProductMeta]
  meta Json?

  // Array of namespace-based types
  /// [Tag]
  tags Json[]

  // Inline union type (enum)
  /// !['physical' | 'digital']
  status String

  // Numeric scalar literal unions
  /// ![1 | 2 | 3]
  priority Int

  // Inline object type
  /// ![{ width: number; height: number }]
  dimensions Json
}

The generator provides compile-time type safety only. To achieve runtime validation, use a library like Zod to define your schema, infer the type, and expose it to the PrismaJson namespace.

1. Define the model in schema.prisma:

   model User {
     id          Int    @id @default(autoincrement())
     /// [UserPreferences]
     preferences Json
   }

2. Define Zod schema and expose type in TypeScript:

   import { z } from 'zod';
   
   export const UserPreferencesSchema = z.object({
     theme: z.enum(['light', 'dark']),
     language: z.string().optional()
   });
   
   declare global {
     namespace PrismaJson {
       type UserPreferences = z.infer<typeof UserPreferencesSchema>;
     }
   }

import { z } from 'zod';

// 1. Define the Zod schema as the source of truth.
export const UserPreferencesSchema = z.object({
  theme: z.enum(['light', 'dark']),
  language: z.string().optional()
});

// 2. Expose the inferred type to Prisma.
declare global {
  namespace PrismaJson {
    type UserPreferences = z.infer<typeof UserPreferencesSchema>;
  }
}

To strongly type a Json field, follow these steps:

1. Add the generator to your schema.prisma:

   generator client {
     provider = "prisma-client"
   }
   
   generator json {
     provider = "prisma-json-types-generator"
   }

2. Define your types in a TypeScript module (e.g., src/types.ts) inside the PrismaJson global namespace:

   export {};
   
   declare global {
     namespace PrismaJson {
       type UserProfile = {
         theme: 'dark' | 'light';
         twitterHandle?: string;
       };
     }
   }

3. Link the type in your Prisma schema using the /// [TypeName] AST comment syntax:

   model User {
     id      Int    @id @default(autoincrement())
     profile Json
   
     /// [UserProfile]
     profile Json
   }

4. Generate the client:

   npx prisma generate

import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

async function updateUserProfile() {
  const user = await prisma.user.update({
    where: { id: 1 },
    data: {
      profile: {
        theme: 'dark'
      }
    }
  });

  // user.profile is now fully typed as UserProfile!
  console.log(user.profile.theme);
}