Neon Auth for React

Neon Auth lets you add authentication to your app in seconds — user data is synced directly to your Neon Postgres database, so you can query and join it just like any other table.

1. Add Neon Auth to a project

   Go to pg.new to create a new Neon project.

   Once your project is ready, open your project's Auth page. Neon Auth is ready for you to get started.

   Click Setup instructions to continue.

   

2. Get your Neon Auth keys

   In the Setup instructions tab, click Set up Auth.

   This gets you the Neon Auth environment variables and connection string you need to integrate Neon Auth and connect to your database.

   You can use these keys right away to get started, or skip ahead to try out user creation in the Neon Console.

   # Neon Auth environment variables for React (Vite)
   
   VITE_STACK_PROJECT_ID=YOUR_NEON_AUTH_PROJECT_ID
   VITE_STACK_PUBLISHABLE_CLIENT_KEY=YOUR_NEON_AUTH_PUBLISHABLE_KEY
   STACK_SECRET_SERVER_KEY=YOUR_NEON_AUTH_SECRET_KEY
   
   # Your Neon connection string
   
   DATABASE_URL=YOUR_NEON_CONNECTION_STRING

   Are you a Vercel user?

   If you're using the Neon native integration on Vercel, the integration automatically sets these environment variables for you in Vercel when you connect a Vercel project to a Neon database. Learn more.

3. Set up your app

   Clone our template for the fastest way to see Neon Auth in action.

   git clone https://github.com/neondatabase-labs/neon-auth-react-template.git

   Or add Neon Auth to an existing project.

   Install the React SDK

   Make sure you have a React project set up. We show an example here of a Vite React project with React Router.

   npm install @stackframe/react

   Use your environment variables

   Paste the Neon Auth environment variables from the Get your Neon Auth keys section into your .env.local file.

4. Configure Neon Auth client

   A basic example of how to set up the Neon Auth client in stack.ts in your src directory:

   import { StackClientApp } from '@stackframe/react';
   import { useNavigate } from 'react-router-dom';
   
   export const stackClientApp = new StackClientApp({
   projectId: import.meta.env.VITE_STACK_PROJECT_ID,
   publishableClientKey: import.meta.env.VITE_STACK_PUBLISHABLE_CLIENT_KEY,
   tokenStore: 'cookie',
   redirectMethod: { useNavigate },
   });

5. Update your app to use the provider and handler

   In your src/App.tsx:

   import { StackHandler, StackProvider, StackTheme } from '@stackframe/react';
   import { Suspense } from 'react';
   import { BrowserRouter, Route, Routes, useLocation } from 'react-router-dom';
   import { stackClientApp } from './stack';
   
   function HandlerRoutes() {
   const location = useLocation();
   
   return (
   <StackHandler app={stackClientApp} location={location.pathname} fullPage />
   );
   }
   
   export default function App() {
   return (
   <Suspense fallback={null}>
   <BrowserRouter>
   <StackProvider app={stackClientApp}>
   <StackTheme>
   <Routes>
   <Route path="/handler/*" element={<HandlerRoutes />} />
   <Route path="/" element={<div>hello world</div>} />
   </Routes>
   </StackTheme>
   </StackProvider>
   </BrowserRouter>
   </Suspense>
   );
   }

6. Start and test your app

   npm start

   Go to http://localhost:3000/handler/sign-up in your browser. Create a user or two, and you can see them show up immediately in the database.

7. Create users in the Console (optional)

   You can create test users directly from the Neon Console — no app integration required. This is useful for development or testing.

   

   Now you can see your users in the database.

8. See your users in the database

   As users sign up or log in — through your app or by creating test users in the Console — their profiles are synced to your Neon database in the neon_auth.users_sync table.

   Query your users table in the SQL Editor to see your new user:

   SELECT * FROM neon_auth.users_sync;

   id	name	email	created_at	updated_at	deleted_at	raw_json
   51e491df...	Sam Patel	sam@startup.dev	2025-02-12 19:43...	2025-02-12 19:46...	null	{"id": "51e491df...", ...}

Next Steps

Want to learn more or go deeper?

• How Neon Auth works — See a before and after showing the benefits of having your user data right in your database
• Neon Auth tutorial — Walk through our demo app for more examples of how Neon Auth can simplify your code
• Best Practices & FAQ — Tips, patterns, and troubleshooting
• Neon Auth API Reference — Automate and manage Neon Auth via the API