From 69a21208627fabcc63dd2198efb462eb1eef0d37 Mon Sep 17 00:00:00 2001 From: ArthurGamby Date: Tue, 17 Feb 2026 11:22:23 +0100 Subject: [PATCH] docs: add Deno runtime guide --- .../content/docs/guides/runtimes/deno.mdx | 317 ++++++++++++++++++ .../content/docs/guides/runtimes/meta.json | 2 +- 2 files changed, 318 insertions(+), 1 deletion(-) create mode 100644 apps/docs/content/docs/guides/runtimes/deno.mdx diff --git a/apps/docs/content/docs/guides/runtimes/deno.mdx b/apps/docs/content/docs/guides/runtimes/deno.mdx new file mode 100644 index 0000000000..846cb55568 --- /dev/null +++ b/apps/docs/content/docs/guides/runtimes/deno.mdx @@ -0,0 +1,317 @@ +--- +title: Deno +description: Learn how to use Prisma ORM in a Deno application with Prisma Postgres +url: /guides/runtimes/deno +--- + +## Introduction + +[Deno](https://deno.com) is a secure JavaScript and TypeScript runtime built on V8 with built-in TypeScript support, a permissions system, and web-standard APIs. In this guide, you will set up a Deno project with Prisma ORM and a Prisma Postgres database. You will create a simple HTTP server that reads from the database and returns the results. + +## Prerequisites + +- [Deno](https://docs.deno.com/runtime/#install-deno) v2.0 or later installed on your system +- A [Prisma Postgres database](/postgres) (created during setup) +- Basic knowledge of JavaScript/TypeScript +- [Deno extension for VS Code](https://docs.deno.com/runtime/reference/vscode/) (recommended) + +## 1. Setting up your Deno project + +First, create a directory for your project and navigate to it: + +```bash +mkdir deno-prisma +cd deno-prisma +``` + +Then, initialize a new Deno project: + +```bash +deno init +``` + +This creates a basic Deno project with a `deno.json` configuration file and a `main.ts` file. + +### 1.1. Configure Deno for Prisma + +Update the `deno.json` file with the following configuration to set up Node.js compatibility, import maps, and Prisma-related task scripts: + +```json title="deno.json" +{ + "nodeModulesDir": "auto", + "compilerOptions": { + "lib": ["deno.window"], + "types": ["node"] + }, + "imports": { + "@prisma/adapter-pg": "npm:@prisma/adapter-pg@^7.0.0", + "@prisma/client": "npm:@prisma/client@^7.0.0", + "prisma": "npm:prisma@^7.0.0" + }, + "tasks": { + "dev": "deno run -A --env=.env --watch main.ts", + "db:generate": "deno run -A --env=.env npm:prisma generate", + "db:push": "deno run -A --env=.env npm:prisma db push", + "db:migrate": "deno run -A --env=.env npm:prisma migrate dev", + "db:seed": "deno run -A --env=.env npm:prisma db seed" + } +} +``` + +:::info + +The `nodeModulesDir: "auto"` setting allows Deno to automatically manage a `node_modules` directory, which is needed for Prisma's generated client. The import map entries let you use bare specifiers like `@prisma/client` in your code. + +::: + +## 2. Installing and configuring Prisma + +### 2.1. Initialize Prisma ORM with Prisma Postgres + +Initialize Prisma ORM with Prisma Postgres in your project: + +```bash +deno run -A npm:prisma init --db +``` + +:::info + +You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for your database like "My Deno Project". + +::: + +This command creates: + +- A `prisma/` directory with your `schema.prisma` file +- A new Prisma Postgres database +- A `prisma.config.ts` file +- A `.env` file with your `DATABASE_URL` + +### 2.2. Update the Prisma config file + +Open the generated `prisma.config.ts` file. Since Deno loads environment variables using the `--env=.env` flag (configured in `deno.json` tasks), you can remove the `dotenv/config` import if it was generated: + +```typescript title="prisma.config.ts" +import "dotenv/config"; // [!code --] +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +### 2.3. Configure environment variables for direct connection + +We're going to use a direct connection string for connecting to Prisma Postgres. To get your [direct connection string](/postgres/database/direct-connections#how-to-connect-to-prisma-postgres-via-direct-tcp): + +1. Navigate to your recently created Prisma Postgres project dashboard (e.g. "My Deno Project") +2. Click the **API Keys** tab in the project's sidebar +3. Click the **Create API key** button +4. Provide a name for the API key and click **Create** +5. Copy the connection string starting with `postgres://` + +Update your `.env` file to replace the `DATABASE_URL` with the new connection string: + +```text title=".env" +DATABASE_URL="your_database_url_here" // [!code --] +DATABASE_URL="your_direct_connection_string_here" // [!code ++] +``` + +### 2.4. Update your Prisma schema + +Open `prisma/schema.prisma` and update it to include the Deno runtime and your data model: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../generated/prisma" + runtime = "deno" // [!code ++] +} + +datasource db { + provider = "postgresql" +} + +model User { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] +} // [!code ++] +``` + +:::note + +The `runtime = "deno"` setting in the generator block is required for Prisma Client to work correctly with the Deno runtime. + +::: + +## 3. Generate Prisma Client and run migrations + +Generate the Prisma Client and apply your schema to the database: + +```bash +deno task db:migrate --name init +deno task db:generate +``` + +This command: + +- Creates the database tables based on your schema +- Generates the Prisma Client in the `generated/prisma` directory + +## 4. Setting up database configuration and creating a seed script + +### 4.1. Create a database utility file + +Create a `db.ts` file in your project root to configure `PrismaClient`: + +```typescript title="db.ts" +import { PrismaClient } from "./generated/prisma/client.ts"; +import { PrismaPg } from "@prisma/adapter-pg"; + +const adapter = new PrismaPg({ + connectionString: Deno.env.get("DATABASE_URL")!, +}); + +export const prisma = new PrismaClient({ + adapter, +}); +``` + +### 4.2. Create a seed script + +Create a seed script in the `prisma` folder to populate your database with sample data: + +```typescript title="prisma/seed.ts" +import { PrismaClient } from "../generated/prisma/client.ts"; +import { PrismaPg } from "@prisma/adapter-pg"; + +const adapter = new PrismaPg({ + connectionString: Deno.env.get("DATABASE_URL")!, +}); + +const prisma = new PrismaClient({ + adapter, +}); + +async function main() { + // Create multiple users + await prisma.user.createMany({ + data: [ + { email: "alice@example.com", name: "Alice" }, + { email: "bob@example.com", name: "Bob" }, + { email: "charlie@example.com", name: "Charlie" }, + { email: "diana@example.com", name: "Diana" }, + { email: "eve@example.com", name: "Eve" }, + { email: "frank@example.com", name: "Frank" }, + { email: "grace@example.com", name: "Grace" }, + { email: "henry@example.com", name: "Henry" }, + { email: "isabella@example.com", name: "Isabella" }, + { email: "jack@example.com", name: "Jack" }, + ], + skipDuplicates: true, // prevents errors if you run the seed multiple times + }); + + console.log("Seed data inserted!"); +} + +main() + .catch((e) => { + console.error(e); + Deno.exit(1); + }) + .finally(async () => { + await prisma.$disconnect(); + }); +``` + +### 4.3. Add the seed script to Prisma Config + +Update the `prisma.config.ts` file to include the seed command: + +```typescript title="prisma.config.ts" +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + seed: "deno run -A --env=.env ./prisma/seed.ts", // [!code ++] + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +Run the seed script to populate your database: + +```bash +deno task db:seed +``` + +## 5. Creating your Deno server + +Replace the `main.ts` file contents with the following code to build a simple HTTP server that uses Prisma ORM to fetch and display users: + +```typescript title="main.ts" +import { prisma } from "./db.ts"; + +async function handler(req: Request): Promise { + const { pathname } = new URL(req.url); + + // Skip favicon route + if (pathname === "/favicon.ico") { + return new Response(null, { status: 204 }); + } + + // Return all users + const users = await prisma.user.findMany(); + + // Count all users + const count = await prisma.user.count(); + + // Format the response with JSON + return new Response( + JSON.stringify({ + users: users, + totalUsers: count, + }), + { headers: { "Content-Type": "application/json" } }, + ); +} + +Deno.serve({ port: 8000 }, handler); +``` + +## 6. Running your application + +Start your Deno server: + +```bash +deno task dev +``` + +You should see the server running on `http://localhost:8000` in the console. When you visit `http://localhost:8000` in your browser, you'll see a JSON response with all the users in your database and the total count. + +## Next steps + +Now that you have a Deno application connected to a Prisma Postgres database, you can continue by: + +- Extending your Prisma schema with additional models and relationships +- Implementing authentication and authorization +- Adding input validation with Zod +- Exploring Deno's built-in testing tools +- Deploying your application to [Deno Deploy](/guides/integrations/deno) + +### More info + +- [Deno Documentation](https://docs.deno.com) +- [Prisma Config File](/orm/reference/prisma-config-reference) +- [Prisma Postgres](/postgres) diff --git a/apps/docs/content/docs/guides/runtimes/meta.json b/apps/docs/content/docs/guides/runtimes/meta.json index dbc70b8022..a28a3b2a2e 100644 --- a/apps/docs/content/docs/guides/runtimes/meta.json +++ b/apps/docs/content/docs/guides/runtimes/meta.json @@ -1 +1 @@ -{"title":"Runtimes","pages":["bun"]} +{"title":"Runtimes","pages":["bun","deno"]}