diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx index 8b4dcf23f9..2592533e17 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx @@ -79,7 +79,7 @@ This module provides several features to streamline the setup and usage of Prism 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. Prompt you to start the [Prisma Studio](/orm/tools/prisma-studio) + 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. diff --git a/content/800-guides/1100-using-prisma-nuxt-module-with-prisma-postgres.mdx b/content/800-guides/1100-using-prisma-nuxt-module-with-prisma-postgres.mdx new file mode 100644 index 0000000000..405a1e8a66 --- /dev/null +++ b/content/800-guides/1100-using-prisma-nuxt-module-with-prisma-postgres.mdx @@ -0,0 +1,259 @@ +--- +title: 'Using Prisma Postgres with the Prisma Nuxt Module' +metaTitle: 'Build a Nuxt app with Prisma Postgres and deploy it on Vercel' +description: 'A step-by-step guide to setting up and using Prisma Postgres with the Prisma Nuxt module and deploying to Vercel.' +sidebar_label: 'Prisma Postgres with Prisma Nuxt Module' +image: '/img/guides/prisma-postgres-and-prisma-nuxt-guide.png' +tags: + - Nuxt + - Prisma Postgres + - Vercel +--- + +The [Prisma Nuxt module](/orm/more/help-and-troubleshooting/prisma-nuxt-module) helps you get started with Prisma in [Nuxt](https://nuxt.com/) applications by simplifying the initial setup process. This guide explains how to set up a Nuxt application, configure [Prisma Postgres](https://prisma.io/postgres) using the Prisma Nuxt module, and deploy the project to [Vercel](https://vercel.com/) for production. + +Here's what you'll learn: + +- How to set up a Nuxt project with the Prisma Nuxt module. +- How to configure and use Prisma Postgres with the Prisma Nuxt module in your Nuxt app. +- How to deploy the project to Vercel. + +## Prerequisites + +To follow this guide, ensure you have the following: + +- Node.js version: A [compatible Node.js version](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6#minimum-supported-nodejs-versions) required for Prisma 6. +- Accounts: + - [GitHub](https://github.com) + - [Prisma Data Platform](https://console.prisma.io) + - [Vercel](https://vercel.com) +- Basic knowledge of Git and Vercel deployment (helpful but not required). + +## 1. Create a New Nuxt Project and set up the Prisma Nuxt module + +1. Initialize [a new Nuxt project](https://nuxt.com/docs/getting-started/installation#new-project), select `npm` as the package manager and initialize git: + ```terminal + npx nuxi@latest init hello-world + ``` + :::note + We recommend using `npm` as it is the most stable option with the `@prisma/nuxt` module. + ::: + +2. Navigate into the project directory and install the `@prisma/nuxt` module: + ```terminal + cd hello-world + npm i @prisma/nuxt + ``` +3. Install the [Prisma Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate) as it's required to use Prisma Postgres: + ```terminal + npm i @prisma/extension-accelerate + ``` +4. Add the `@prisma/nuxt` module with the following configuration to your `nuxt.config.ts` file: + ```typescript + // https://nuxt.com/docs/api/configuration/nuxt-config + export default defineNuxtConfig({ + compatibilityDate: "2024-11-01", + modules: ["@prisma/nuxt"], + experimental: { + componentIslands: true, + }, + devtools: { enabled: true }, + }); + ``` + +## 2. Setup Prisma ORM by running the development server locally + +After configuring your Nuxt project with the Prisma module, the next step is to set up Prisma ORM. This process begins by starting the development server, which automatically configures Prisma with a [SQLite database](/orm/overview/databases/sqlite). + +Run the following command to start the development server: + +```terminal +npm run dev +``` + +After running this command, you will be prompted to run a database migration with [Prisma Migrate](/orm/prisma-migrate/understanding-prisma-migrate/overview): + +```terminal +? Do you want to migrate database changes to your database? › (Y/n) +``` + +Confirm that you want to migrate your database and create your initial tables by hitting Y on your keyboard. + +Once the setup flow has terminated, it: + +1. Installed the [Prisma CLI](/orm/reference/prisma-cli-reference). +2. Initialized a Prisma project with a SQLite database. +3. Created sample `User` and `Post` models in the `schema.prisma` 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-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. Created the database tables for the `User` and `Post` models from the previous steps. + :::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. Installed and generated [Prisma Client](https://da-2255.docs-51g.pages.dev/orm/reference/prisma-client-reference) which enables you to query your DB. +6. Installed [Prisma Studio](/orm/tools/prisma-studio). + +When the Prisma setup is complete, the development server should start on `https://localhost:3000`. + +Next, stop the server, as we need to make some code changes. + +## 4. Update the application code + +With Prisma configured, the next step is to update your application code to fetch and display data from your database. + +1. In the root directory of your project, create a folder named `components`. + +2. Inside the `components` folder, create a file named `User.server.vue`. This server component will fetch and display the name of the first user from the database: + ```html file=components/User.server.vue + + + + ``` + + :::note + We're extending the `usePrismaClient()` composable with the `withAccelerate()` extension method to ensure [compatibility with Prisma Postgres](/orm/overview/databases/prisma-postgres#using-the-client-extension-for-prisma-accelerate-required). This extension will also allow you to [cache your queries](/accelerate/caching). + ::: + +3. Modify the `app.vue` file in the root directory to include the new server component using Nuxt Islands: + ```html file=app.vue + + ``` + +4. Run the following command to start the development server again: + ```terminal + npm run dev + ``` +5. Verify the application code is working by opening your application in a browser at `https://localhost:3000`. + As there are no users in the database yet, the application will display: + ```no-copy + No user has been added yet. + ``` + This message will dynamically update when users are added to your database. + +By completing these steps, your application is now capable of fetching data from your Prisma database and rendering it on the frontend. + +## 5. Create a Prisma Postgres instance + +Now create a Prisma Postgres database instance using the Prisma Data Platform: + +1. Navigate to [Prisma Data Platform](https://console.prisma.io). +2. Click **New project** to create a new project. +3. Enter a name for your project in the **Name** field. +4. Inside the **Prisma Postgres®** section, click **Get started**. +5. Choose a region close to your location from the **Region** dropdown. +6. Click **Create project** to set up your database. This redirects you to the database setup page. +7. In the **Set up database access** section, copy the `DATABASE_URL`. You will use this in the next steps. + +At this point, you have successfully created a Prisma Postgres instance. + +## 6. Set up Prisma Postgres in your Nuxt app + +Now that the Prisma Postgres instance is ready, update your Nuxt application to use this database: + +1. Update the `.env` file by replacing the existing `DATABASE_URL` value with the one you previously copied. It will look similar to this: + ```terminal file=.env + // edit-next-line + DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=PRISMA_POSTGRES_API_KEY" + ``` + +2. Modify the `schema.prisma` file by changing the database provider in the `datasource` block of the `schema.prisma` file located in the `prisma` folder: + ```prisma file=prisma/schema.prisma + datasource db { + // edit-next-line + provider = "postgresql" + url = env("DATABASE_URL") + } + ``` +3. Delete the SQLite database files (`dev.db` and `dev.db-journal`) along with the `migrations` folder, all located in the `prisma` directory. This cleans up the existing SQLite setup and prepares your project to migrate to PostgreSQL. +4. Manually create a new migration for the Postgres database by running the `prisma migrate` command: + ```terminal + npx prisma migrate dev --name init + ``` +5. Start the development server again: + ```terminal + npm run dev + ``` +6. Open the Nuxt DevTools (by hitting Shift+Option+ D) and click the Prisma logo in the left sidenav to open Prisma Studio. Then add a new `User` record by specifying values for the `name` and `email` fields. +7. Verify the data in the application by refreshing your application at `https://localhost:3000`. The page should display the name of the user you added in Prisma Studio. For example, if you added a user named `Jon`, the application will display `Jon` in the browser. + +Congratulations, your Nuxt app is now fully integrated with Prisma Postgres! + +## 7. Deploy to Vercel + +Deploy your Nuxt application with Prisma Postgres integration to Vercel by following these steps: + +1. Ensure your project is version-controlled and pushed to a GitHub repository. If you don’t have a repository yet, [create one on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). Once the repository is ready, run the following commands: + ```terminal + git add . + git commit -m "Initial commit with Prisma Postgres integration" + git branch -M main + git remote add origin https://github.com//.git + git push -u origin main + ``` + :::note + Replace `` and `` with your GitHub username and the name of your repository. + ::: +2. Log in to [Vercel](https://vercel.com/) and navigate to your [Dashboard](https://vercel.com/docs/dashboard-features). +3. Create a new project. Follow Vercel's [Import an existing project](https://vercel.com/docs/getting-started-with-vercel/import) guide, but stop at [step 3](https://vercel.com/docs/getting-started-with-vercel/import#optionally-configure-any-settings) where you will configure environment variables _before_ clicking **Deploy**. +4. Configure the `DATABASE_URL` environment variable: + 1. Expand the **Environment variables** section. + 2. Add the `DATABASE_URL` environment variable: + - **Key**: `DATABASE_URL` + - **Value**: Paste your Prisma Postgres connection URL, e.g. by copying it from the `.env` file in your Nuxt project. + :::warning + Do not deploy without setting the `DATABASE_URL` variable. Your deployment will fail if the application cannot connect to the database. + ::: +5. Click the **Deploy** button. Vercel will build your project and deploy it to a live URL. +6. Open the live URL provided by Vercel and verify that your application is working: + - If you’ve added a user in Prisma Studio, their name should appear on the live site. + - If no users exist, the application will display: + ``` + No user has been added yet. + ``` +7. To add or manage data: + 1. Open Prisma Studio via [the Prisma Data Platform](https://prisma.io/blog/studio-for-prisma-postgres-view-and-edit-your-data-online) or local instance. + 2. Add or update user data in the database. + 3. Refresh your live site to confirm the changes. + +Congratulations! Your Nuxt application with Prisma Postgres integration is now live and fully operational on Vercel. + +## Considerations + +This guide helps you get started with Prisma Postgres using the Nuxt module. Because the Nuxt module is actively evolving, it does not cover all of Prisma’s features or support every edge case. For more advanced functionality or edge deployments, consider using Prisma directly. \ No newline at end of file diff --git a/static/img/guides/prisma-postgres-and-prisma-nuxt-guide.png b/static/img/guides/prisma-postgres-and-prisma-nuxt-guide.png new file mode 100644 index 0000000000..853c1e18f9 Binary files /dev/null and b/static/img/guides/prisma-postgres-and-prisma-nuxt-guide.png differ