Connect Nuxt to Postgres on Neon

Pre-built prompt for connecting Nuxt applications to Neon.

Copy prompt

Nuxt 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:

1. Create a Neon project

   Create a Neon project with the Neon CLI or the Console.

   Neon CLIConsole

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

   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.

2. 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 for details. The CLI commands in the next step run from this directory.

      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.

      Neon serverless driverpostgres.jsnode-postgres

      npm install @neondatabase/serverless

3. Store your Neon credentials

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

   Neon CLIConsole

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

   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.

4. 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 driverpostgres.jsnode-postgres

   server/utils/db.ts

   import { neon } from '@neondatabase/serverless';
   
   export const sql = neon(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 driverpostgres.jsnode-postgres

   server/api/version.get.ts

   export default defineEventHandler(async () => {
     const [row] = await sql`SELECT version()`;
     return row;
   });

   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.

5. Run the app

   Start the dev server:

   Terminal

   npm run dev

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

   { "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: Add managed authentication that branches with your database
• Add Object Storage: S3-compatible file storage that branches with your database
• Deploy a Function: Run backend compute next to your database, no separate hosting needed
• Call an LLM with AI Gateway: Access foundation models from Anthropic, OpenAI, Google, and more with one credential
• Realtime: Build realtime apps with end-to-end reactivity »