Skip to content

docs: update nuxt guide #7387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AmanVarshney01 merged 2 commits into from
Dec 16, 2025
Merged

docs: update nuxt guide #7387

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28e6190
docs: update nuxt guide
AmanVarshney01 Dec 13, 2025
0bdfd67
Merge branch 'main' into dr-6475-update-existing-guide-for-nuxt-modul…
AmanVarshney01 Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
370 changes: 1 addition & 369 deletions content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,374 +5,6 @@ metaDescription: 'Learn how to easily add Prisma ORM to your Nuxt apps, use its
community_section: true
---

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

[Prisma ORM](/orm/overview/introduction/what-is-prisma) 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.

:::warning
The `@prisma/nuxt` module is currently not supported with Prisma ORM 7 or when using a custom `generator client { output = ... }`. For Prisma 7 projects, follow the general Nuxt guide instead.
The `@prisma/nuxt` module is deprecated and no longer recommended. Please follow our [Nuxt guide](/guides/nuxt) for the recommended approach to integrating Prisma ORM with your Nuxt application.
:::

## 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](https://nuxt.com/docs/getting-started/installation#new-project):
```terminal
npm create nuxt test-nuxt-app
```

2. Navigate to project directory and install `@prisma/nuxt` using the Nuxt CLI:
```terminal
cd test-nuxt-app
npx nuxi@latest module add @prisma/nuxt
```
<br />
:::warning

If you're using `pnpm`, make sure to hoist Prisma dependencies. Follow the [Prisma studio steps](#prisma-studio-not-opening-with-pnpm) for detailed instructions.

:::

3. Start the development server:
```terminal
npm run dev
```

Starting the development server will:
1. Automatically install the [Prisma CLI](/orm/reference/prisma-cli-reference)
2. Initialize a Prisma project with SQLite
3. Create an `User` and `Post` example model in the Prisma Schema file:
```prisma 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"
output = "./generated"
}

datasource db {
provider = "sqlite"
}

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](/orm/prisma-migrate/understanding-prisma-migrate/overview)
:::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](/orm/prisma-migrate/workflows/troubleshooting) any migration-related errors.
:::
5. Install and generate a [Prisma Client](/orm/reference/prisma-client-reference) which enables you to query your DB
6. Automatically start [Prisma Studio](/orm/tools/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](#usage) 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](/orm/reference/supported-databases). You can configure the [getting started example](#getting-started) to use a database of your choice. The steps would be different for a [database without existing data](#using-a-database-without-existing-data) and a [database with pre-existing data](#using-a-database-with-pre-existing-data).

### Using a database without existing data

To configure [the getting started example](#getting-started) to use a PostgreSQL database without any existing data:

1. Stop the Nuxt development server and Prisma Studio (if they are still running):
```terminal
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 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"
output = "./generated"
}

datasource db {
provider = "postgresql"
}

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
}
```
2. Update the `DATABASE_URL` environment variable in the `.env` file with your PostgreSQL database URL:
```.env file=.env
## This is a sample database URL, please use a valid URL
DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
```
3. Delete the SQLite database file and the migrations folder:
```terminal
rm prisma/dev.db # Delete SQLite database file
rm -r prisma/migrations # Delete the pre-existing migrations folder
```
4. Run the development server:
```terminal
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.
5. The `@prisma/nuxt` module is ready to use with your PostgreSQL database. See the [usage section](#usage) to learn how to use Prisma Client in your app.

### Using a database with pre-existing data

To configure [the getting started example](#getting-started) to use a PostgreSQL database that already has data in it:

1. Stop the dev server and Prisma Studio (if they are still running):
```terminal
// 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:
```terminal
rm -r prisma/
```
3. Update the `DATABASE_URL` environment variable in the `.env` file with your PostgreSQL database URL:
```.env file=.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](/orm/prisma-schema/introspection) the database. Complete **step 1** to **step 4** from the [introspection guide](/orm/prisma-migrate/getting-started#adding-prisma-migrate-to-an-existing-project) 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](#usage) 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](https://nuxt.com/docs/guide/directory-structure/components#server-components), you can use the global instance of the Prisma Client in your `.server.vue` files:
```html
<script setup>
const prisma = usePrismaClient()
const user = await prisma.user.findFirst()
</script>

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

### 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.
```typescript file=lib/prisma.ts
import { PrismaClient } from '../prisma/generated/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 [Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate):

```typescript file=lib/prisma.ts
import { PrismaClient } from '../prisma/generated/client'
import { withAccelerate } from '@prisma/extension-accelerate'

const prismaClientSingleton = () => {
return new PrismaClient().$extends(withAccelerate())
}

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
```
<br/>
:::info

Use the `prisma` instance from the `lib` folder if you want to leverage a client using [Prisma Client extensions](/orm/prisma-client/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:
```typescript
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](https://nuxt.com/docs/guide/directory-structure/components#server-components), you can use the global instance of the Prisma Client `.server.vue` files:
```html
<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`:

```ts file=nuxt.config.ts
export default defineNuxtConfig({
// ...
prisma: {
// Options
}
})
```
<br />
:::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](/orm/tools/prisma-cli). |
| **installClient** | `boolean` | true | Whether to install the [Prisma Client](/orm/prisma-client) library in the project. |
| **generateClient** | `boolean` | true | Whether to [generate](/orm/prisma-client/setup-and-configuration/generating-prisma-client) 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](/orm/reference/prisma-cli-reference#format) the [Prisma Schema](/orm/prisma-schema) file. |
| **installStudio** | `boolean` | true | Whether to install and start [Prisma Studio](https://www.prisma.io/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. |
| **skipPrompts** | `false` | false | Skips all prompts |
| **prismaRoot** | `string` | false | Required when using [Nuxt layers](https://nuxt.com/docs/getting-started/layers). For example, if you have a Nuxt layer called `database`, the `prismaRoot` would be `./database` in the base nuxt config. This refers to the folder where Prisma will be initialized or checked. |
| **prismaSchemaPath** | `string` | `undefined` | Required when using [Nuxt layers](https://nuxt.com/docs/getting-started/layers). For example, if you have a Nuxt layer called `database`, the `prismaSchemaPath` would be `./database/prisma/schema.prisma` in the base nuxt config. |
| **runMigration** | `boolean` | true | Whether to run a Prisma Migration automatically. If you are using MongoDB or PlanetScale, use the [`npx prisma db push` command](/orm/prisma-migrate/workflows/prototyping-your-schema#choosing-db-push-or-prisma-migrate). Migrations aren’t supported for these databases, so this command will ensure your schema is updated appropriately. |

## Limitations

### `PrismaClient` constructor options are not configurable in the `usePrismaClient` composable

The `usePrismaClient` module does not currently allow for configuration of `PrismaClient` [constructor options](/orm/reference/prisma-client-reference#prismaclient).

### 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](https://pris.ly/discord?utm_source=docs&utm_medium=inline_text) or [GitHub](https://github.com/prisma/nuxt-prisma).

## Troubleshooting

### Prisma Studio not opening with `pnpm`

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

```terminal
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 file=.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:

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

### Limitations in package manager support

The module is designed to work with popular package managers, including npm, Yarn, and pnpm. However, as of `v0.2`, it is not fully compatible with Bun due to an issue causing an indefinite installation loop.

Additionally, this package has not been tested with Deno and is therefore not officially **supported.**

### Resolving `Error: @prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.`

If you encounter the following message even if you have generated the client.

```terminal
Error: @prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.
```

Please try delete `output = ../generated/prisma` in schema.prisma, like

```prisma file=prisma/schema.prisma
generator client {
provider = "prisma-client"
output = "./generated"
}
```

When you specify a custom output directory for the Prisma Client, it means that the generated client code will not be located in the default `node_modules/@prisma/client directory`. Instead, it will be generated in your project's root directory under `generated/prisma/`. However, the `@prisma/nuxt` module in Nuxt expects to find `PrismaClient` in the default `@prisma/client` location.
Loading
Loading