Skip to main content

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
  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

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

OptionTypeDefaultDescription
installCLIbooleantrueWhether to install the Prisma CLI.
installClientbooleantrueWhether to install the Prisma Client library in the project.
generateClientbooleantrueWhether to generate the PrismaClient instance. Executes npx prisma generate on every run to update the client based on the schema changes.
formatSchemabooleantrueWhether to format the Prisma Schema file.
installStudiobooleantrueWhether to install and start Prisma Studio in the Nuxt Devtools.
autoSetupPrismabooleanfalseWhether 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.