Next.js + MotherDuck Postgres endpoint quickstart

The Next.js + MotherDuck Postgres endpoint quickstart is a dashboard template that creates an interactive NYC Taxi analytics dashboard with the Next.js App Router, querying MotherDuck over the Postgres endpoint through the standard pg driver.

What is the Next.js + MotherDuck Postgres endpoint quickstart?

This template is a reference implementation that connects a Next.js application to MotherDuck's public sample_data.nyc.taxi share using the Postgres endpoint. It takes a MotherDuck access token and an optional host as environment variables, and outputs a server-rendered dashboard with KPI cards, Recharts charts, a date-range picker, and a click-to-drill day view. The project is designed to deploy directly to Vercel via a one-click button or the MotherDuck Native Integration from the Vercel Marketplace.

Key Features

• App Router home page — src/app/page.tsx server-renders the usable date bounds for the dataset, then hands off to a client dashboard component.
• Parallel aggregate queries — src/app/api/dashboard/route.ts runs six parameterized queries in parallel for a given start/end range: KPIs, trips-per-day, pickups-by-hour, revenue-by-payment-type, payment-to-rate Sankey, and top pickup zones.
• Bounds API — src/app/api/bounds/route.ts returns the minimum and maximum days that have meaningful trip volume, keeping the date picker on populated data.
• Reusable connection pool — src/lib/motherduck.ts creates a pg.Pool with SSL, registers it with attachDatabasePool from @vercel/functions, and shuts it down cleanly on Vercel Fluid Compute.
• Interactive client dashboard — src/components/dashboard.tsx provides KPI cards, Recharts line/bar/Sankey charts, click-to-drill day view, and a bounded date-range picker.
• shadcn/ui components — Includes button, card, calendar, date-range-picker, popover, separator, and skeleton.
• Tailwind CSS v4 with Geist fonts — The UI uses Tailwind CSS v4 and the Geist font family, with dark mode enabled by default.

Who is it for?

• Next.js developers who want a working example of connecting to MotherDuck through the Postgres endpoint using the pg driver.
• Data analysts who need to quickly visualize DuckDB-powered datasets like the NYC taxi public share without building from scratch.
• Vercel users exploring Fluid Compute and the MotherDuck Native Integration for managed database provisioning.

What can you do with it?

• Deploy a live analytics dashboard instantly by using the Vercel deploy button; the template comes pre-wired to MotherDuck's public sample_data share, so it works as soon as it is deployed.
• Explore NYC taxi data interactively with the date picker and click-to-drill: select any point on the trips-per-day line chart to see a single day's detailed view.
• Repoint the template at your own data by changing the DATABASE constant in src/lib/motherduck.ts and providing your own MotherDuck token.

How does it work?

The MotherDuck Postgres endpoint makes MotherDuck speak the Postgres wire protocol, so any Postgres client such as pg can execute DuckDB SQL. This template creates one pg.Pool, registers it with attachDatabasePool for graceful shutdown on Fluid Compute, and route handlers borrow clients from the pool to run parameterized queries in parallel with Promise.all, returning JSON to the frontend.

FAQ

Do I need a MotherDuck account?

Yes. A free MotherDuck account works for this template; you can sign up at app.motherduck.com. You will need an access token from the settings page, which you paste into the MOTHERDUCK_TOKEN environment variable.

What data does the dashboard query?

It queries MotherDuck's public sample_data.nyc.taxi share, so the dashboard is populated immediately after deployment without setting up any tables. The database name is hard-coded in src/lib/motherduck.ts.

Can I use my own database?

Yes. Change the DATABASE constant in src/lib/motherduck.ts to point at your own MotherDuck database, and keep your token in MOTHERDUCK_TOKEN. The six dashboard queries and the bounds query will then run against your data.

What environment variables are required?

Only MOTHERDUCK_TOKEN is required. MOTHERDUCK_HOST is optional; if absent, it defaults to pg.us-east-1-aws.motherduck.com, which matches the default region for new MotherDuck accounts.

What are the prerequisites for local development?

You need Node.js 20 or later, plus a MotherDuck account. After cloning, run npm install, copy .env.example to .env.local, add your token, and start with npm run dev.