Skip to content

Commit b698252

Browse files
AmanVarshney01AmanVarshney01
authored
docs: update nuxt guide (#7387)
1 parent 2485d01 commit b698252

File tree

2 files changed

+205
-640
lines changed

2 files changed

+205
-640
lines changed

‎content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx‎

Lines changed: 1 addition & 369 deletions
Original file line numberDiff line numberDiff line change
@@ -5,374 +5,6 @@ metaDescription: 'Learn how to easily add Prisma ORM to your Nuxt apps, use its
55
community_section: true
66
---
77

8-
The Nuxt Prisma module simplifies the integration of Prisma ORM into your Nuxt applications.
9-
10-
[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.
11-
12-
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.
13-
148
:::warning
15-
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.
9+
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.
1610
:::
17-
18-
## Features
19-
20-
- **Project initialization**: Automatically sets up a Prisma ORM project with a SQLite database within your Nuxt project.
21-
- **Composable**: Provides an auto-imported `usePrismaClient()` composable for use in your Vue files.
22-
- **API route integration**: Automatically imports an instance of `PrismaClient` for use in API routes to query your DB.
23-
- **Prisma Studio access**: Enables access to Prisma Studio through Nuxt Devtools for viewing and manually editing data.
24-
25-
## Getting started
26-
27-
1. Create a [new Nuxt Project](https://nuxt.com/docs/getting-started/installation#new-project):
28-
```terminal
29-
npm create nuxt test-nuxt-app
30-
```
31-
32-
2. Navigate to project directory and install `@prisma/nuxt` using the Nuxt CLI:
33-
```terminal
34-
cd test-nuxt-app
35-
npx nuxi@latest module add @prisma/nuxt
36-
```
37-
<br />
38-
:::warning
39-
40-
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.
41-
42-
:::
43-
44-
3. Start the development server:
45-
```terminal
46-
npm run dev
47-
```
48-
49-
Starting the development server will:
50-
1. Automatically install the [Prisma CLI](/orm/reference/prisma-cli-reference)
51-
2. Initialize a Prisma project with SQLite
52-
3. Create an `User` and `Post` example model in the Prisma Schema file:
53-
```prisma file=prisma/schema.prisma
54-
// This is your Prisma schema file,
55-
// learn more about it in the docs: https://pris.ly/d/prisma-schema
56-
57-
generator client {
58-
provider = "prisma-client"
59-
output = "./generated"
60-
}
61-
62-
datasource db {
63-
provider = "sqlite"
64-
}
65-
66-
model User {
67-
id Int @id @default(autoincrement())
68-
email String @unique
69-
name String?
70-
posts Post[]
71-
}
72-
73-
model Post {
74-
id Int @id @default(autoincrement())
75-
title String
76-
content String?
77-
published Boolean @default(false)
78-
author User @relation(fields: [authorId], references: [id])
79-
authorId Int
80-
}
81-
```
82-
4. Prompt you to run a migration to create database tables with [Prisma Migrate](/orm/prisma-migrate/understanding-prisma-migrate/overview)
83-
:::note
84-
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.
85-
:::
86-
5. Install and generate a [Prisma Client](/orm/reference/prisma-client-reference) which enables you to query your DB
87-
6. Automatically start [Prisma Studio](/orm/tools/prisma-studio)
88-
89-
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.
90-
91-
## Using a different database provider
92-
93-
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).
94-
95-
### Using a database without existing data
96-
97-
To configure [the getting started example](#getting-started) to use a PostgreSQL database without any existing data:
98-
99-
1. Stop the Nuxt development server and Prisma Studio (if they are still running):
100-
```terminal
101-
npx kill-port 3000 # Stops Nuxt dev server (default port)
102-
npx kill-port 5555 # Stops Prisma Studio (default port)
103-
```
104-
2. Navigate to the `schema.prisma` file and update the `datasource` block to specify the `postgresql` provider:
105-
```prisma file=prisma/schema.prisma
106-
// This is your Prisma schema file,
107-
// learn more about it in the docs: https://pris.ly/d/prisma-schema
108-
109-
generator client {
110-
provider = "prisma-client"
111-
output = "./generated"
112-
}
113-
114-
datasource db {
115-
provider = "postgresql"
116-
}
117-
118-
model User {
119-
id Int @id @default(autoincrement())
120-
email String @unique
121-
name String?
122-
posts Post[]
123-
}
124-
125-
model Post {
126-
id Int @id @default(autoincrement())
127-
title String
128-
content String?
129-
published Boolean @default(false)
130-
author User @relation(fields: [authorId], references: [id])
131-
authorId Int
132-
}
133-
```
134-
2. Update the `DATABASE_URL` environment variable in the `.env` file with your PostgreSQL database URL:
135-
```.env file=.env
136-
## This is a sample database URL, please use a valid URL
137-
DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
138-
```
139-
3. Delete the SQLite database file and the migrations folder:
140-
```terminal
141-
rm prisma/dev.db # Delete SQLite database file
142-
rm -r prisma/migrations # Delete the pre-existing migrations folder
143-
```
144-
4. Run the development server:
145-
```terminal
146-
npm run dev
147-
```
148-
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.
149-
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.
150-
151-
### Using a database with pre-existing data
152-
153-
To configure [the getting started example](#getting-started) to use a PostgreSQL database that already has data in it:
154-
155-
1. Stop the dev server and Prisma Studio (if they are still running):
156-
```terminal
157-
// stops Nuxt dev server from running incase it's still running
158-
npx kill-port 3000
159-
// stops Prisma Studio instance incase it's still running
160-
npx kill-port 5555
161-
```
162-
2. Delete the Prisma folder:
163-
```terminal
164-
rm -r prisma/
165-
```
166-
3. Update the `DATABASE_URL` environment variable in the `.env` file with your PostgreSQL database URL:
167-
```.env file=.env
168-
## This is a sample database URL, please use a valid URL
169-
DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
170-
```
171-
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.
172-
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.
173-
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.
174-
175-
## Usage
176-
177-
### Option A: `usePrismaClient` composable
178-
179-
#### Using the composable in your Nuxt server component
180-
181-
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:
182-
```html
183-
<script setup>
184-
const prisma = usePrismaClient()
185-
const user = await prisma.user.findFirst()
186-
</script>
187-
188-
<template>
189-
<p>{{ user.name }}</p>
190-
</template>
191-
```
192-
193-
### Option B: `lib/prisma.ts`
194-
195-
After running through the initial setup prompts, this module creates the `lib/prisma.ts` file which contains a global instance of Prisma Client.
196-
```typescript file=lib/prisma.ts
197-
import { PrismaClient } from '../prisma/generated/client'
198-
199-
const prismaClientSingleton = () => {
200-
return new PrismaClient()
201-
}
202-
203-
declare const globalThis: {
204-
prismaGlobal: ReturnType<typeof prismaClientSingleton>;
205-
} & typeof global;
206-
207-
const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()
208-
209-
export default prisma
210-
211-
if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma
212-
```
213-
214-
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):
215-
216-
```typescript file=lib/prisma.ts
217-
import { PrismaClient } from '../prisma/generated/client'
218-
import { withAccelerate } from '@prisma/extension-accelerate'
219-
220-
const prismaClientSingleton = () => {
221-
return new PrismaClient().$extends(withAccelerate())
222-
}
223-
224-
declare const globalThis: {
225-
prismaGlobal: ReturnType<typeof prismaClientSingleton>;
226-
} & typeof global;
227-
228-
const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()
229-
230-
export default prisma
231-
232-
if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma
233-
```
234-
<br/>
235-
:::info
236-
237-
Use the `prisma` instance from the `lib` folder if you want to leverage a client using [Prisma Client extensions](/orm/prisma-client/client-extensions).
238-
239-
:::
240-
241-
#### Using the global Prisma Client instance in your API route
242-
243-
You can use the global instance of the Prisma Client in your Nuxt API route as follows:
244-
```typescript
245-
import prisma from "~/lib/prisma";
246-
247-
export default defineEventHandler(async (event) => {
248-
return {
249-
user: await prisma.user.findFirst(),
250-
};
251-
});
252-
```
253-
254-
#### Using the global Prisma Client instance in your Nuxt server component
255-
256-
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:
257-
```html
258-
<script setup>
259-
import prisma from '~/lib/prisma';
260-
const user = await prisma.user.findFirst()
261-
</script>
262-
263-
<template>
264-
<p>{{ user.name }}</p>
265-
</template>
266-
```
267-
268-
## Configuration
269-
270-
You can configure the `@prisma/nuxt` module by using the `prisma` key in `nuxt.config.ts`:
271-
272-
```ts file=nuxt.config.ts
273-
export default defineNuxtConfig({
274-
// ...
275-
prisma: {
276-
// Options
277-
}
278-
})
279-
```
280-
<br />
281-
:::note
282-
The `prisma` key is available in `nuxt.config.ts` after successfully setting up the module by running `npm run dev`
283-
:::
284-
285-
| Option | Type | Default | Description |
286-
|---------------------|-----------|---------|-------------|
287-
| **installCLI** | `boolean` | true | Whether to install the [Prisma CLI](/orm/tools/prisma-cli). |
288-
| **installClient** | `boolean` | true | Whether to install the [Prisma Client](/orm/prisma-client) library in the project. |
289-
| **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. |
290-
| **formatSchema** | `boolean` | true | Whether to [format](/orm/reference/prisma-cli-reference#format) the [Prisma Schema](/orm/prisma-schema) file. |
291-
| **installStudio** | `boolean` | true | Whether to install and start [Prisma Studio](https://www.prisma.io/studio) in the Nuxt Devtools. |
292-
| **autoSetupPrisma** | `boolean` | false | Whether to skip all prompts during setup. This option is useful for automating Prisma setup in scripts or CI/CD pipelines. |
293-
| **skipPrompts** | `false` | false | Skips all prompts |
294-
| **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. |
295-
| **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. |
296-
| **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. |
297-
298-
## Limitations
299-
300-
### `PrismaClient` constructor options are not configurable in the `usePrismaClient` composable
301-
302-
The `usePrismaClient` module does not currently allow for configuration of `PrismaClient` [constructor options](/orm/reference/prisma-client-reference#prismaclient).
303-
304-
### The `usePrismaClient` composable is not supported in edge runtimes
305-
306-
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).
307-
308-
## Troubleshooting
309-
310-
### Prisma Studio not opening with `pnpm`
311-
312-
If you're encountering the following error when using `pnpm` and Prisma Studio isn't opening:
313-
314-
```terminal
315-
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=*)
316-
```
317-
318-
To resolve this issue, create a `.npmrc` file in your project root and add the following configuration to hoist Prisma dependencies:
319-
320-
```.npmrc file=.npmrc
321-
hoist-pattern[]=*prisma*
322-
```
323-
324-
This will ensure that Prisma dependencies are properly resolved by `pnpm`.
325-
326-
### Resolving `TypeError: Failed to resolve module specifier ".prisma/client/index-browser"`
327-
328-
If you encounter the following error message in the browser console after building and previewing your application:
329-
330-
```
331-
TypeError: Failed to resolve module specifier ".prisma/client/index-browser"
332-
```
333-
To resolve this issue, add the following configuration to your nuxt.config.ts file:
334-
335-
```ts file=nuxt.config.ts
336-
import { defineNuxtConfig } from 'nuxt'
337-
338-
export default defineNuxtConfig({
339-
modules: [
340-
'@prisma/nuxt',
341-
],
342-
// additional config
343-
vite: {
344-
resolve: {
345-
alias: {
346-
'.prisma/client/index-browser': './node_modules/.prisma/client/index-browser.js',
347-
},
348-
},
349-
},
350-
})
351-
```
352-
353-
This configuration ensures that the module specifier is correctly mapped to the appropriate file.
354-
355-
### Limitations in package manager support
356-
357-
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.
358-
359-
Additionally, this package has not been tested with Deno and is therefore not officially **supported.**
360-
361-
### Resolving `Error: @prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.`
362-
363-
If you encounter the following message even if you have generated the client.
364-
365-
```terminal
366-
Error: @prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.
367-
```
368-
369-
Please try delete `output = ../generated/prisma` in schema.prisma, like
370-
371-
```prisma file=prisma/schema.prisma
372-
generator client {
373-
provider = "prisma-client"
374-
output = "./generated"
375-
}
376-
```
377-
378-
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.

0 commit comments

Comments
 (0)