Connect a TanStack Start application to Neon

TanStack Start is an open-source, fully type-safe web framework for building feature rich React and Solid based applications using the TanStack ecosystem.

To create a Neon project and access it from a Start application:

1. Create a Neon project

   If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

   1. Navigate to the Projects page in the Neon Console.
   2. Click New Project.
   3. Specify your project settings and click Create Project.

2. Create a Start project and add dependencies

   1. Create a Start project if you do not have one. For instructions see the quick start guides, in the TanStack documentation.

   2. Add project dependencies using one of the following commands:

      Neon serverless driver

      postgres.js

      node-postgres

      npm install @neondatabase/serverless

3. Store your Neon credentials

   Add a .env file to your project directory and add your Neon connection string to it. You can find your Neon database connection string by clicking the Connect button on your Project Dashboard to open the Connect to your database modal. For more information, see Connect from any application.

   DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require&channel_binding=require"

   If you haven't created a database yet, run the following command to generate a Neon Instagres DB. It will spin up a database instance that you can use for 72 hours, or claim to keep forever.

   npm

   yarn

   pnpm

   bun

   deno

   npm get-db

4. Configure the Postgres client

   There are multiple ways to make server side requests with TanStack Start. See below for the different implementations.

   Server Functions

   In your server functions, add the following code snippet to connect to your Neon database:

   Neon serverless driver

   postgres.js

   node-postgres

   src/data/get-neon-data.ts

   import { neon } from "@neondatabase/serverless";
   import { createServerFn } from "@tanstack/react-start";
   
   export const getData = createServerFn({ method: "GET" }).handler(async () => {
     const sql = neon(process.env.DATABASE_URL);
     const response = await sql`SELECT version()`;
   
     return response[0].version;
   });

   Then consume the data in your start application, like you would normally, with any other data fetching operation.

   src/routes/index.tsx

   import { createFileRoute } from "@tanstack/react-router";
   import { getData } from "../data/get-neon-data.ts";
   
   export const Route = createFileRoute("/")({
     loader: async () => {
       return getData();
     },
   
     component: RouteComponent,
   });
   
   export default function RouteComponent() {
     const data = Route.useLoaderData();
   
     return <>{data}</>;
   }

   Static Server Functions

   In your static server functions, add the following code snippet to connect to your Neon database:

   Neon serverless driver

   postgres.js

   node-postgres

   src/data/get-neon-data.ts

   import { neon } from "@neondatabase/serverless";
   import { createServerFn } from "@tanstack/react-start";
   import { staticFunctionMiddleware } from "@tanstack/start-static-server-functions";
   
   export const getData = createServerFn({ method: "GET" })
   .middleware([staticFunctionMiddleware])
   .handler(async () => {
     const sql = neon(process.env.DATABASE_URL);
     const response = await sql`SELECT version()`;
   
     return response[0].version;
   });

   Then like before you can consume the data in your components.

   Be aware Static Server Functions are executed at build time, and cached as a static asset for pre-rendering or static generation.

   src/routes/index.tsx

   import { createFileRoute } from "@tanstack/react-router";
   import { getData } from "../data/get-neon-data.ts";
   
   export const Route = createFileRoute("/")({
     loader: async () => {
       return getData();
     },
   
     component: RouteComponent,
   });
   
   export default function RouteComponent() {
     const data = Route.useLoaderData();
   
     return <>{data}</>;
   }

5. Run the app

   When you run npm run dev you can expect to see the following on localhost:3000:

   PostgreSQL 16.0 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit

Where to upload and serve files?

Neon does not provide a built-in file storage service. For managing binary file data (blobs), we recommend a pattern that leverages dedicated, specialized storage services. Follow our guide on File Storage to learn more about how to store files in external object storage and file management services and track metadata in Neon.

Source code

You can find the source code for the applications described in this guide on GitHub.

• Get started with TanStack Start Server Functions and Neon

  Get started with TanStack Start Server Functions and Neon

• Get started with TanStack Start Static Server Functions and Neon

  Get started with TanStack Start Static Server Functions and Neon