Using the Nuxt Prisma Module

The Nuxt Prisma module simplifies the integration of Prisma ORM into your Nuxt applications.

Prisma ORM is a database library that lets you model your database schema, provides auto-generated migrations and lets you query the database in an intuitive and type-safe way.

This module provides several features to streamline the setup and usage of Prisma ORM in a Nuxt application, making it easier to interact with your database.

Features

• Project initialization: Automatically sets up a Prisma ORM project with a SQLite database within your Nuxt project.
• Composable: Provides an auto-imported usePrismaClient() composable for use in your Vue files.
• API route integration: Automatically imports an instance of PrismaClient for use in API routes to query your DB.
• Prisma Studio access: Enables access to Prisma Studio through Nuxt Devtools for viewing and manually editing data.

Getting started

1. Create a new Nuxt Project:

   npx nuxi@latest init test-nuxt-app

2. Navigate to project directory and install @prisma/nuxt using the Nuxt CLI:

   cd test-nuxt-app
   npx nuxi@latest module add @prisma/nuxt
   
   
   warning

   If you're using pnpm, make sure to hoist Prisma dependencies. Follow the steps here for detailed instructions.

3. Start the development server:

   npm run dev

   Starting the development server will:

   1. Automatically install the Prisma CLI
   2. Initialize a Prisma project with SQLite
   3. Create an User and Post example model in the Prisma Schema file:
      prisma/schema.prisma

       // This is your Prisma schema file,
       // learn more about it in the docs: https://pris.ly/d/prisma-schema
      
       generator client {
         provider = "prisma-client-js"
       }
      
       datasource db {
         provider = "sqlite"
         url      = env("DATABASE_URL")
       }
      
       model User {
         id    Int     @id @default(autoincrement())
         email String  @unique
         name  String?
         posts Post[]
       }
      
       model Post {
         id        Int     @id @default(autoincrement())
         title     String
         content   String?
         published Boolean @default(false)
         author    User    @relation(fields: [authorId], references: [id])
         authorId  Int
       }
   4. Prompt you to run a migration to create database tables with Prisma Migrate
      note

      The database migrates automatically the first time you start the module if there isn't a migrations folder. After that, you need to run npx prisma migrate dev manually in the CLI to apply any schema changes. Running the npx prisma migrate dev command manually makes it easier and safer to manage migrations and also to troubleshoot any migration-related errors.

   5. Install and generate a Prisma Client which enables you to query your DB
   6. Prompt you to start the Prisma Studio

4. You can now use Prisma ORM in your project. If you accepted the prompt to add Prisma Studio, you can access Prisma Studio through the Nuxt Devtools. See the usage section to learn how to use Prisma Client in your app.

Using a different database provider

The @prisma/nuxt module works with any database provider that Prisma ORM supports. You can configure the getting started example to use a database of your choice. The steps would be different for a database without existing data and a database with pre-existing data.

Using a database without existing data

To configure the getting started example to use a PostgreSQL database without any existing data:

1. Stop the Nuxt development server and Prisma Studio (if they are still running):

   npx kill-port 3000  # Stops Nuxt dev server (default port)
   npx kill-port 5555  # Stops Prisma Studio (default port)
2. Navigate to the schema.prisma file and update the datasource block to specify the postgresql provider:
   prisma/schema.prisma

   // This is your Prisma schema file,
   // learn more about it in the docs: https://pris.ly/d/prisma-schema
   
   generator client {
     provider = "prisma-client-js"
   }
   
   datasource db {
     provider = "postgresql"
     url      = env("DATABASE_URL")
   }
   
   model User {
     id    Int     @id @default(autoincrement())
     email String  @unique
     name  String?
     posts Post[]
   }
   
   model Post {
     id        Int     @id @default(autoincrement())
     title     String
     content   String?
     published Boolean @default(false)
     author    User    @relation(fields: [authorId], references: [id])
     authorId  Int
   }
3. Update the DATABASE_URL environment variable in the .env file with your PostgreSQL database URL:
   .env

   ## This is a sample database URL, please use a valid URL
   DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
4. Delete the SQLite database file and the migrations folder:

   rm prisma/dev.db # Delete SQLite database file
   rm -r prisma/migrations # Delete the pre-existing migrations folder
5. Run the development server:

   npm run dev
   Starting the development server will prompt you to migrate the schema changes to the database, to which you should agree. Then agree to the prompt to install and access Prisma Studio from the Nuxt Devtools.
6. The @prisma/nuxt module is ready to use with your PostgreSQL database. See the usage section to learn how to use Prisma Client in your app.

Using a database with pre-existing data

To configure the getting started example to use a PostgreSQL database that already has data in it:

1. Stop the dev server and Prisma Studio (if they are still running):

   // stops Nuxt dev server from running incase it's still running
   npx kill-port 3000
   // stops Prisma Studio instance incase it's still running
   npx kill-port 5555
2. Delete the Prisma folder:

   rm -r prisma/
3. Update the DATABASE_URL environment variable in the .env file with your PostgreSQL database URL:
   .env

   ## This is a sample database URL, please use a valid URL
   DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
4. To generate a Prisma Schema and migrations folder from the existing database, you have to introspect the database. Complete step 1 to step 4 from the introspection guide and continue.
5. Starting the development server will skip the prompt to migrate the schema changes to the database, as the migrations folder already exists. Agree to the prompt to install and access Prisma Studio from the Nuxt Devtools.
6. The @prisma/nuxt module is ready to be used with your PostgreSQL database. See the usage section to learn how to use Prisma Client in your app.

Usage

Option A: usePrismaClient composable

Using the composable in your Nuxt server component

If you're using Nuxt server components, you can use the global instance of the Prisma Client in your .server.vue files:

<script setup>
  const prisma = usePrismaClient()
  const user = await prisma.user.findFirst()
</script>

<template>
  <p>{{ user.name }}</p>
</template>

Using the auto-imported Prisma Client instance in your API route

You can use the auto-imported Prisma Client instance, prisma, in your Nuxt API route as follows:

export default defineEventHandler(async (event) => {
  return {
    user: await prisma.user.findFirst(),
  };
});

Option B: lib/prisma.ts

After running through the initial setup prompts, this module creates the lib/prisma.ts file which contains a global instance of Prisma Client.

lib/prisma.ts

import { PrismaClient } from '@prisma/client'

const prismaClientSingleton = () => {
  return new PrismaClient()
}

declare const globalThis: {
  prismaGlobal: ReturnType<typeof prismaClientSingleton>;
} & typeof global;

const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()

export default prisma

if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma

You can customize Prisma Client's capabilities by using client extensions in your lib/prisma.ts file. Here is an example using the Pulse client extension:

lib/prisma.ts

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prismaClientSingleton = () => {
  return new PrismaClient().$extends(withPulse({
    apiKey: process.env.PULSE_API_KEY
  }))
}

declare const globalThis: {
  prismaGlobal: ReturnType<typeof prismaClientSingleton>;
} & typeof global;

const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()

export default prisma

if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma

info

Use the prisma instance from the lib folder if you want to leverage a client using Prisma Client extensions.

Using the global Prisma Client instance in your API route

You can use the global instance of the Prisma Client in your Nuxt API route as follows:

import prisma from "~/lib/prisma";

export default defineEventHandler(async (event) => {
  return {
    user: await prisma.user.findFirst(),
  };
});

Using the global Prisma Client instance in your Nuxt server component

If you're using Nuxt server components, you can use the global instance of the Prisma Client .server.vue files:

<script setup>
  import prisma from '~/lib/prisma';
  const user = await prisma.user.findFirst()
</script>

<template>
  <p>{{ user.name }}</p>
</template>

Configuration

You can configure the @prisma/nuxt module by using the prisma key in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  // ...
  prisma: {
    // Options
  }
})

note

The prisma key is available in nuxt.config.ts after successfully setting up the module by running npm run dev

Option	Type	Default	Description
installCLI	boolean	true	Whether to install the Prisma CLI.
installClient	boolean	true	Whether to install the Prisma Client library in the project.
generateClient	boolean	true	Whether to generate the PrismaClient instance. Executes npx prisma generate on every run to update the client based on the schema changes.
formatSchema	boolean	true	Whether to format the Prisma Schema file.
installStudio	boolean	true	Whether to install and start Prisma Studio in the Nuxt Devtools.
autoSetupPrisma	boolean	false	Whether to skip all prompts during setup. This option is useful for automating Prisma setup in scripts or CI/CD pipelines.

Limitations

PrismaClient constructor options are not configurable in the usePrismaClient composable

The usePrismaClient module does not currently allow for configuration of PrismaClient constructor options.

The usePrismaClient composable is not supported in edge runtimes

The usePrismaClient composable currently relies on a PrismaClient instance that does not work in edge runtimes. If you require edge support for the composable, please let us know on Discord or GitHub.

Troubleshooting

Prisma Studio not opening with pnpm

If you're encountering the following error when using pnpm and Prisma Studio isn't opening:

Uncaught SyntaxError: The requested module '/_nuxt/node_modules/.pnpm/*@*/node_modules/@prisma/client/index-browser.js?v=' does not provide an export named 'PrismaClient' (at plugin.mjs?v=*)

To resolve this issue, create a .npmrc file in your project root and add the following configuration to hoist Prisma dependencies:

.npmrc

hoist-pattern[]=*prisma*

This will ensure that Prisma dependencies are properly resolved by pnpm.

Resolving TypeError: Failed to resolve module specifier ".prisma/client/index-browser"

If you encounter the following error message in the browser console after building and previewing your application:

TypeError: Failed to resolve module specifier ".prisma/client/index-browser" 

To resolve this issue, add the following configuration to your nuxt.config.ts file:

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  modules: [
    '@prisma/nuxt',
  ],
  // additional config
  vite: {
    resolve: {
      alias: {
        '.prisma/client/index-browser': './node_modules/.prisma/client/index-browser.js',
      },
    },
  },
})

This configuration ensures that the module specifier is correctly mapped to the appropriate file.