> This page location: Frontend & Frameworks > Frameworks > Nuxt
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Connect Nuxt (Vue meta-framework) to serverless Postgres on Neon: use the Neon CLI to create the project and pull DATABASE_URL into your .env, then run SQL from a Nitro server route with the Neon serverless driver. Choose this guide when building a full-stack Nuxt app that needs server-side Postgres queries, covering CLI setup, driver selection (Neon serverless driver, node-postgres, or postgres.js), and reading the connection string in server code.

# Connect Nuxt to Postgres on Neon

Learn how to make server-side queries to Postgres using Nitro API routes

Last updated: 2026-10-08

Pre-built prompt for connecting Nuxt applications to Neon. [View prompt](https://neon.com/prompts/nuxt-neon-prompt.md)

[Nuxt](https://nuxt.com/) is an open-source full-stack meta framework that enables Vue-based web applications. This topic describes how to connect a Nuxt application to a Postgres database on Neon.

To create a Neon project and access it from a Nuxt.js application:

## Create a Neon project

Create a Neon project with the [Neon CLI](https://neon.com/docs/cli/install) or the Console.

**Neon CLI**

Install the CLI (`npm i -g neon`), then sign in and create the project:

```bash filename="Terminal"
neon login
neon projects create --name my-app
```

If you belong to more than one organization, the CLI prompts you to choose one. To skip the prompt, pass `--org-id <id>` (find it with `neon orgs list`).

You'll link this project and pull its credentials in a later step.

**Console**

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Nuxt project and add dependencies

1. Create a Nuxt project if you do not have one, then change into its directory. The scaffolder is interactive (it asks about the template, package manager, git, and modules); for CI or an AI agent, pass those as flags to run non-interactively. See [Create a Nuxt Project](https://nuxt.com/docs/getting-started/installation#new-project) for details. The CLI commands in the next step run from this directory.

   ```bash filename="Terminal"
   # Interactive (human):
   npm create nuxt@latest my-app && cd my-app

   # Non-interactive (CI / AI agents):
   npm create nuxt@latest my-app -- --template minimal --packageManager npm --no-gitInit --modules "" && cd my-app
   ```

2. Add a Postgres driver. This guide's examples use the Neon serverless driver, which suits serverless and edge deployments; for long-lived servers, `pg` or `postgres.js` are recommended. See [Choosing your connection method](https://neon.com/docs/connect/choose-connection).

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

## Store your Neon credentials

Get your `DATABASE_URL` into a `.env` file the app can read.

**Neon CLI**

From your project directory, link the app to your Neon project and pull its connection string:

```bash filename="Terminal"
neon link                    # connects this directory to your project (writes .neon)
neon env pull --file .env    # writes DATABASE_URL from your default branch into .env
```

Notes:

- Not signed in yet? Run `neon login` first.
- `neon link` prompts for an org and project. To skip the prompts, pass `--org-id <id>` and `--project-id <id>` (find IDs with `neon orgs list` and `neon projects list`), plus `--branch <name>` to pin a branch, or `-y` to pin the default branch.
- For Nuxt, pass in `--file .env` to `neon env pull` as it writes to `.env.local` by default, and `nuxt dev` only reads `.env` by default.
- Which branch? `neon env pull` uses your project's default branch: `main` for CLI-created projects, `production` for Console-created ones (`neon branches list` shows yours). To use a different branch, run `neon checkout <branch>` first; it re-pins the branch in `.neon` so the next `env pull` reads from it.

**Console**

Add a `.env` file and paste your connection string, which you can copy from the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell filename=".env"
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

## Configure the Postgres client

The connection string is a server-side secret, so query it from Nitro server code, which reads `process.env.DATABASE_URL` directly (no `runtimeConfig` needed).

Create a server utility that holds the database client. Use the tab for the driver you installed:

**Neon serverless driver**

```typescript filename="server/utils/db.ts"
import { neon } from '@neondatabase/serverless';

export const sql = neon(process.env.DATABASE_URL!);
```

**postgres.js**

```typescript filename="server/utils/db.ts"
import postgres from 'postgres';

export const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });
```

**node-postgres**

```typescript filename="server/utils/db.ts"
import pg from 'pg';

export const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
```

Then use it in a server API route. Files in `server/utils/` are auto-imported, so `sql` (or `pool`) is available without an import:

**Neon serverless driver**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const [row] = await sql`SELECT version()`;
  return row;
});
```

**postgres.js**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const [row] = await sql`SELECT version()`;
  return row;
});
```

**node-postgres**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const { rows } = await pool.query('SELECT version()');
  return rows[0];
});
```

To type-check the server code with `npx nuxt typecheck`, install `typescript`, `vue-tsc`, and `@types/node` as dev dependencies (`npm install -D typescript vue-tsc @types/node`).

If you use node-postgres, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` in `.env` to keep the same behavior without the warning.

**Note:** Keep the database client in `server/` only. Never import `server/utils/db.ts` from a Vue component or `app/` code; the connection string must stay server-side.

## Run the app

Start the dev server:

```bash filename="Terminal"
npm run dev
```

Then open `localhost:3000/api/version`. The route returns your Postgres version, confirming the connection:

```json
{ "version": "PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc ..." }
```

`nuxt dev` loads `.env`, but the production server doesn't. After `npm run build`, start it with the variable in its environment, for example `node --env-file=.env .output/server/index.mjs`.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/quickstart): Build realtime apps with end-to-end reactivity »

---

## Related docs (Frameworks)

- [Astro](https://neon.com/docs/guides/astro)
- [Bun](https://neon.com/docs/guides/bun)
- [Entity Framework](https://neon.com/docs/guides/dotnet-entity-framework)
- [Encore](https://neon.com/docs/guides/encore)
- [Express](https://neon.com/docs/guides/express)
- [Medusa.js](https://neon.com/docs/guides/medusajs)
- [Micronaut Kotlin](https://neon.com/docs/guides/micronaut-kotlin)
- [NestJS](https://neon.com/docs/guides/nestjs)
- [Next.js](https://neon.com/docs/guides/nextjs)
- [Node.js](https://neon.com/docs/guides/node)
- [Phoenix](https://neon.com/docs/guides/phoenix)
- [Quarkus (JDBC)](https://neon.com/docs/guides/quarkus-jdbc)
- [Quarkus (Reactive)](https://neon.com/docs/guides/quarkus-reactive)
- [React](https://neon.com/docs/guides/react)
- [React Router](https://neon.com/docs/guides/react-router)
- [Reflex](https://neon.com/docs/guides/reflex)
- [Remix](https://neon.com/docs/guides/remix)
- [SolidStart](https://neon.com/docs/guides/solid-start)
- [Sveltekit](https://neon.com/docs/guides/sveltekit)
- [Symfony](https://neon.com/docs/guides/symfony)
- [TanStack Start](https://neon.com/docs/guides/tanstack-start)
- [Hono](https://neon.com/docs/guides/hono)
- [RedwoodSDK](https://neon.com/docs/guides/redwoodsdk)
- [Vue](https://neon.com/docs/guides/vue)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/guides/nuxt"}` to https://feedback.neon.tech/ (no auth required).