Prisma JSON Types Generator

4.1.1 · active · verified Sun Apr 19

The `prisma-json-types-generator` is a development-time tool that enhances the Prisma client by providing strict TypeScript typings for `Json` and `String` fields, replacing Prisma's default `JsonValue` with custom, user-defined interfaces. The current stable version is `4.1.1`, which primarily supports Prisma 7 and above, with earlier `v3.x` releases supporting Prisma 6. This package operates during the `prisma generate` step, ensuring all type transformations occur at compile-time without introducing any runtime overhead. Its release cadence generally follows major Prisma version updates, with patch releases for bug fixes and minor improvements. Key differentiators include robust type-safety for complex JSON structures, the ability to define string literal enums without relying on native database enums, flexible type configuration through global namespaces or inline annotations, and compatibility with multiple Prisma clients in a single project. It works seamlessly across all database drivers supported by Prisma.

Common errors

```
Property 'someJsonField' does not exist on type 'Prisma.JsonValue'.
```
cause The `prisma-json-types-generator` has not run, is incorrectly configured, or an incompatible version of Prisma/generator is in use, preventing the custom JSON types from being applied.

fix Ensure `prisma generate` has been run after configuring the generator in `schema.prisma`. Verify `prisma-json-types-generator` is correctly listed as a generator provider and that its version is compatible with your installed `prisma` and `@prisma/client` versions (v4+ for Prisma 7+, v3 for Prisma 6).
```
Type 'string' is not assignable to type 'Prisma.NullableJsonNullValueInput<string> | MyCustomType'.
```
cause This error often indicates issues with Prisma 7's required `Prisma.` namespace prefix for certain input types that the generator modifies, specifically for `NullableJsonNullValueInput` or `UpdateInput` types.

fix Update `prisma-json-types-generator` to version `4.0.1` or later, which contains fixes for correctly applying the `Prisma.` namespace prefix in generated types.

Warnings

breaking Upgrading to `prisma-json-types-generator` v4.x requires Prisma version 7 or newer. Older Prisma versions (v6 and below) are only supported by `prisma-json-types-generator` v3.x and earlier. Mixing incompatible versions will lead to type generation errors.
Fix: For Prisma 7+, use `prisma-json-types-generator@^4`. For Prisma 6 and below, use `prisma-json-types-generator@^3`.
gotcha Versions `3.6.2` and below had a significant "Maintenance Status Update" indicating a change in the project's maintenance approach (see GitHub issue #542 for details). While v4.x is actively maintained, users on v3.x should be aware of this historical context regarding project stability.
Fix: Review GitHub issue #542 for details on the v3.x maintenance status. Consider upgrading to v4.x and Prisma 7 for active development and support.
gotcha Early v4.x versions (e.g., `4.0.0-beta.1` to `4.0.0`) could produce incorrect types for `UpdateInput` and `NullableJsonNullValueInput` due to missing `Prisma.` namespace prefixes when used with Prisma 7. These issues were resolved in `v4.0.0-beta.2` and `v4.0.1`.
Fix: Upgrade to `prisma-json-types-generator@4.0.1` or later to ensure correct type generation for update inputs with Prisma 7.
gotcha Previous versions might have incorrectly typed JSON fields for models with lowercase names in `groupBy` operations. This was addressed in `v4.0.0`.
Fix: Ensure you are on `prisma-json-types-generator@4.0.0` or higher for correct typing in `groupBy` scenarios involving JSON fields and lowercase model names.
gotcha Types generated on `where` inputs for nullable integer/float fields without explicit type annotations were incorrect in versions prior to `v4.1.1`.
Fix: Upgrade to `prisma-json-types-generator@4.1.1` or later to fix type generation for nullable `Int` or `Float` fields in `where` clauses without explicit annotations.

Install

npm install prisma-json-types-generator npm
yarn add prisma-json-types-generator yarn
pnpm add prisma-json-types-generator pnpm

Quickstart

This quickstart demonstrates how to configure the `prisma-json-types-generator` in `schema.prisma` to apply custom TypeScript types to a `Json` field. It then shows how to interact with the Prisma client, benefiting from compile-time type-safety and autocompletion for the `settings` field.

/* schema.prisma */
generator client {
  provider = "prisma-client-js"
}

generator json {
  provider  = "prisma-json-types-generator"
  namespace = "PrismaJson" // Optional: define a custom namespace for generated types
  allowAny  = false
}

model User {
  id        String @id @default(uuid())
  settings  Json   @db.Text @PrismaJson.UserSettings // Apply custom type
}

/// @PrismaJson.UserSettings
type UserSettings = {
  theme: "dark" | "light";
  notifications: boolean;
  preferences?: { locale: string; timezone: string; };
}

/* index.ts */
import { PrismaClient } from '@prisma/client';
import { UserSettings } from './@prisma/client'; // Import generated type (adjust path as needed if namespace is used)

const prisma = new PrismaClient();

async function main() {
  // Example: Create a user with strongly typed JSON settings
  const user = await prisma.user.create({
    data: {
      settings: {
        theme: 'dark',
        notifications: true,
        preferences: { locale: 'en-US', timezone: 'UTC' }
      },
    },
  });

  console.log('Created user:', user);
  // Accessing settings provides full TypeScript autocompletion and type-checking
  console.log('User theme:', user.settings.theme); // 'dark'

  // Example: Update user settings with type-safety
  const updatedUser = await prisma.user.update({
    where: { id: user.id },
    data: {
      settings: {
        theme: 'light', // Autocompletion for 'dark' | 'light'
        notifications: false,
        preferences: { locale: 'es-ES', timezone: 'America/Mexico_City' }
      },
    },
  });

  console.log('Updated user:', updatedUser);
  // If you try to assign an invalid type, TypeScript will catch it at compile time.
  // e.g., updatedUser.settings.theme = 'invalid'; // Type error

}

main().catch(console.error).finally(() => prisma.$disconnect());

view raw JSON →