### Next.js Quickstart for Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Get started with Neon Auth in your Next.js application. This guide covers the initial setup and integration steps.

```nextjs
See /docs/neon-auth/quick-start/nextjs
```

--------------------------------

### React Quickstart for Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Begin using Neon Auth with your React application. This guide provides instructions for a quick setup.

```react
See /docs/neon-auth/quick-start/react
```

--------------------------------

### JavaScript Quickstart for Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Integrate Neon Auth into your JavaScript applications. This guide outlines the necessary steps for a smooth integration.

```javascript
See /docs/neon-auth/quick-start/javascript
```

--------------------------------

### Install Neon Auth SDK

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/javascript.md

Installs the Neon Auth JavaScript SDK using npm.

```bash
npm install @stackframe/js
```

--------------------------------

### Next.js Setup with Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/nextjs.md

Provides instructions for setting up Neon Auth in a Next.js (App Router) project using the `@stackframe/init-stack` CLI. It details running the setup wizard, configuring environment variables, and testing the integration.

```bash
npx @stackframe/init-stack@latest --no-browser

# This sets up auth routes, layout wrappers, and handlers automatically for Next.js (App Router).

# Use your environment variables
# Paste the Neon Auth environment variables from [Step 2](#get-your-neon-auth-keys) into your `.env.local` file.
# Then `npm run dev` to start your dev server.

# Test your integration
# Go to [http://localhost:3000/handler/sign-up](http://localhost:3000/handler/sign-up) in your browser. Create a user or two, and you can see them [show up immediately](#see-your-users-in-the-database) in your database.
```

--------------------------------

### Install Neon Auth SDK for React

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/react.md

Installs the Neon Auth React SDK using npm. This is a prerequisite for using Neon Auth in your React project.

```bash
npm install @stackframe/react
```

--------------------------------

### SQL Foreign Key Examples for Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/best-practices.md

Demonstrates how to define foreign key constraints with different ON DELETE behaviors for Neon Auth user data. Includes examples for personal data (CASCADE) and content data (SET NULL).

```sql
-- For personal data that should be removed with the user (e.g., todos)
CREATE TABLE todos (
    id SERIAL PRIMARY KEY,
    task TEXT NOT NULL,
    user_id UUID NOT NULL REFERENCES neon_auth.users_sync(id) ON DELETE CASCADE,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);

-- For content that should persist after user deletion (e.g., blog posts)
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    author_id UUID REFERENCES neon_auth.users_sync(id) ON DELETE SET NULL,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
```

--------------------------------

### Custom Profile Page Example

Source: https://github.com/curtis-arch/neon-docs/blob/main/get-started/accessing-user-data.md

An example of a client component that displays user information such as display name and primary email, and provides options to sign in, sign up, or sign out. It utilizes `useUser`, `useStackApp`, and `UserButton`.

```tsx
'use client';
import { useUser, useStackApp, UserButton } from '@stackframe/stack';

export default function PageClient() {
  const user = useUser();
  const app = useStackApp();
  return (
    <div>
      {user ? (
        <div>
          <UserButton />
          <p>Welcome, {user.displayName ?? 'unnamed user'}</p>
          <p>Your e-mail: {user.primaryEmail}</p>
          <button onClick={() => user.signOut()}>Sign Out</button>
        </div>
      ) : (
        <div>
          <p>You are not logged in</p>
          <button onClick={() => app.redirectToSignIn()}>Sign in</button>
          <button onClick={() => app.redirectToSignUp()}>Sign up</button>
        </div>
      )}
    </div>
  );
}
```

--------------------------------

### Create a Team

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/orgs-and-teams.md

Provides examples for creating a new team. The client-side example adds the current user to the team with default creator permissions. The server-side example creates a team without associating a specific user.

```tsx
const team = await user.createTeam({
  displayName: 'New Team',
});
```

```javascript
const team = await stackServerApp.createTeam({
  displayName: 'New Team',
});
```

--------------------------------

### SQL Query for Neon Auth User Data with LEFT JOIN

Source: https://github.com/curtis-arch/neon-docs/blob/main/best-practices.md

An example SQL query demonstrating how to join with the `users_sync` table using a LEFT JOIN and filter for non-deleted users, suitable for handling potential sync delays.

```sql
SELECT posts.*, neon_auth.users_sync.name as author_name
FROM posts
LEFT JOIN neon_auth.users_sync ON posts.author_id = neon_auth.users_sync.id
WHERE neon_auth.users_sync.deleted_at IS NULL;
```

--------------------------------

### SignUp Component Usage

Source: https://github.com/curtis-arch/neon-docs/blob/main/components/sign-up.md

Example of how to use the SignUp component from '@stackframe/stack' in a React application. It demonstrates setting various props like fullPage, automaticRedirect, firstTab, and extraInfo.

```tsx
import { SignUp } from '@stackframe/stack';

export default function Page() {
  return (
    <div>
      <h1>Sign Up</h1>
      <SignUp
        fullPage={true}
        automaticRedirect={true}
        firstTab="password"
        extraInfo={
          <>
            By signing up, you agree to our <a href="/terms">Terms</a>
          </>
        }
      />
    </div>
  );
}
```

--------------------------------

### Install next-themes

Source: https://github.com/curtis-arch/neon-docs/blob/main/customization/dark-mode.md

Installs the next-themes package, which is used for managing theme switching in React applications.

```bash
npm install next-themes
```

--------------------------------

### useStackApp Hook Example

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/hooks/use-stack-app.md

Demonstrates how to use the useStackApp hook to retrieve the StackClientApp object and access its properties, like signIn URL.

```jsx
import { useStackApp } from '@stackframe/stack';

function MyComponent() {
  const stackApp = useStackApp();
  return <div>Sign In URL: {stackApp.urls.signIn}</div>;
}
```

--------------------------------

### Setup Internationalization with StackProvider

Source: https://github.com/curtis-arch/neon-docs/blob/main/customization/internationalization.md

Demonstrates how to pass the `lang` prop to the `StackProvider` component to set the application's language. If no language is provided, it defaults to 'en-US'.

```jsx
  <StackProvider ... lang={'de-DE'}>
    ...
  </StackProvider>
```

--------------------------------

### CredentialSignIn Component Usage

Source: https://github.com/curtis-arch/neon-docs/blob/main/components/credential-sign-in.md

Example of how to import and use the CredentialSignIn component within a React page.

```tsx
import { CredentialSignIn } from '@stackframe/stack';

export default function Page() {
  return (
    <div>
      <h1>Sign In</h1>
      <CredentialSignIn />
    </div>
  );
}
```

--------------------------------

### Protect Page with Middleware

Source: https://github.com/curtis-arch/neon-docs/blob/main/get-started/accessing-user-data.md

Provides an example of using middleware to protect pages. It checks if a user is logged in and redirects them to the sign-in page if they are not.

```javascript
import { stackServerApp } from '@/stack';

export async function middleware(request) {
  const user = await stackServerApp.getUser();
  if (!user) {
    return Response.redirect(new URL('/handler/sign-in', request.url));
  }
  return Response.next();
}
```

--------------------------------

### Using Onboarding Check in Client Component (React/Next.js)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/user-onboarding.md

This example shows how to integrate the `useOnboarded` client-side hook into a React component. It calls the hook at the top of the component to ensure the user is onboarded before rendering the main content. It also displays a welcome message using the user's display name.

```jsx
import {
  useOnboarding
} from '@/app/onboarding-hooks';
import {
  useUser
} from '@stackframe/stack';

export default function HomePage() {
  useOnboarding();
  const user = useUser();

  return (

    <div>Welcome to the app, {user.displayName}</div>
  );
}
```

--------------------------------

### Next.js SDK Integration

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/types/team-user.md

Example of integrating the Neon Auth TeamUser SDK in a Next.js application.

```javascript
import { TeamUser } from '@neon-auth/sdk';

// Assuming you have initialized the SDK elsewhere
// const neonAuth = new NeonAuth({ apiKey: 'YOUR_API_KEY' });

// Example usage within a Next.js component
function MyComponent() {
  // const teamUser = new TeamUser(neonAuth);
  // ... use teamUser methods here
  return <div>Neon Auth TeamUser SDK Example</div>;
}
```

--------------------------------

### Neon Auth Project Permissions Matrix

Source: https://github.com/curtis-arch/neon-docs/blob/main/permissions-roles.md

Details the actions that Neon Auth Admins, Members, and Collaborators can perform within a Neon project. This matrix outlines capabilities like installing, removing, claiming projects, generating SDK keys, and creating users.

```markdown
| Action            | Admin | Member | Collaborator |
| ------------------ | :---: | :----: | :----------: |
| Install Neon Auth |  ✅   |   ❌   |      ❌      |
| Remove Neon Auth  |  ✅   |   ❌   |      ❌      |
| Claim project     |  ✅   |   ❌   |      ❌      |
| Generate SDK Keys |  ✅   |   ❌   |      ❌      |
| Create users      |  ✅   |   ✅   |      ✅      |
```

--------------------------------

### StackServerApp API Documentation

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/objects/stack-server-app.md

Provides methods for interacting with user and team data within the StackServer application. Includes functions for getting, listing, and creating users and teams, with both direct retrieval and reactive hooks.

```APIDOC
StackServerApp:
  __constructor(options)
    Initializes a new instance of StackServerApp.
    Parameters:
      options: Configuration options for the server app.
    Returns: A new StackServerApp instance.

  getUser(id?, options?): Promise<ServerUser|null>
    Retrieves a user by their ID. If no ID is provided, it attempts to get the current user.
    Parameters:
      id: The ID of the user to retrieve (optional).
      options: Additional options for fetching the user (optional).
    Returns: A Promise that resolves to the ServerUser object or null if not found.

  useUser(id?, options?): ServerUser
    A reactive hook to get a user by their ID. Automatically updates when user data changes.
    Parameters:
      id: The ID of the user to retrieve (optional).
      options: Additional options for fetching the user (optional).
    Returns: The ServerUser object.

  listUsers(options?): Promise<ServerUser[]>
    Retrieves a list of all users.
    Parameters:
      options: Additional options for filtering or paginating the user list (optional).
    Returns: A Promise that resolves to an array of ServerUser objects.

  useUsers(options?): ServerUser[]
    A reactive hook to get a list of users. Automatically updates when the user list changes.
    Parameters:
      options: Additional options for filtering or paginating the user list (optional).
    Returns: An array of ServerUser objects.

  createUser(options?): Promise<ServerUser>
    Creates a new user.
    Parameters:
      options: An object containing the data for the new user (optional).
    Returns: A Promise that resolves to the newly created ServerUser object.

  getTeam(id): Promise<ServerTeam|null>
    Retrieves a team by its ID.
    Parameters:
      id: The ID of the team to retrieve.
    Returns: A Promise that resolves to the ServerTeam object or null if not found.

  useTeam(id): ServerTeam
    A reactive hook to get a team by its ID. Automatically updates when team data changes.
    Parameters:
      id: The ID of the team to retrieve.
    Returns: The ServerTeam object.

  listTeams(): Promise<ServerTeam[]>
    Retrieves a list of all teams.
    Returns: A Promise that resolves to an array of ServerTeam objects.

  useTeams(): ServerTeam[]
    A reactive hook to get a list of teams. Automatically updates when the team list changes.
    Returns: An array of ServerTeam objects.
```

--------------------------------

### Using Onboarding Check in Server Component (Next.js)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/user-onboarding.md

This example demonstrates how to use the `ensureOnboarded` server-side function in a Next.js server component. The function is called to enforce onboarding before the component renders, ensuring that only onboarded users can access this content. It then fetches and displays the user's display name.

```jsx
import {
  ensureOnboarding
} from '@/app/onboarding-functions';
import {
  stackServerApp
} from '@/stack';

export default async function HomePage() {
  await ensureOnboarding();
  const user = await stackServerApp.getUser();

  return (
    <div>Welcome to the app, {user.displayName}</div>
  );
}
```

--------------------------------

### Joining User Data with Application Tables

Source: https://github.com/curtis-arch/neon-docs/blob/main/tutorial.md

Shows an example of joining the `neon_auth.users_sync` table with another application table (e.g., 'posts') to retrieve related data, such as posts along with the author's name. This highlights the ease of integrating synchronized user data into your application's queries.

```SQL
SELECT posts.*, neon_auth.users_sync.name AS author_name
FROM posts
JOIN neon_auth.users_sync ON posts.author_id = neon_auth.users_sync.id;
```

--------------------------------

### Team Page with SelectedTeamSwitcher (Deep Link + Most Recent Team)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/team-selection.md

Example of a Next.js page that displays team information and integrates the SelectedTeamSwitcher for deep linking. It fetches user data and a specific team based on URL parameters.

```tsx
'use client';

import { useUser, SelectedTeamSwitcher } from '@stackframe/stack';

export default function TeamPage({ params }: { params: { teamId: string } }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(params.teamId);

  if (!team) {
    return <div>Team not found</div>;
  }

  return (
    <div>
      <SelectedTeamSwitcher urlMap={(team) => `/team/${team.id}`} selectedTeam={team} />

      <p>Team Name: {team.displayName}</p>
      <p>You are a member of this team.</p>
    </div>
  );
}
```

--------------------------------

### Neon Auth Demo & Tutorial

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Explore a practical demonstration of Neon Auth and follow a tutorial to see it in action.

```video
See /docs/neon-auth/demo
```

--------------------------------

### Neon Auth Best Practices

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Learn tips, patterns, and troubleshooting advice for effectively using Neon Auth.

```tips
See /docs/neon-auth/best-practices
```

--------------------------------

### React Template

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

A starter template for building React applications with Neon Auth.

```github
See https://github.com/neondatabase-labs/neon-auth-react-template
```

--------------------------------

### Clone Neon Auth Demo App

Source: https://github.com/curtis-arch/neon-docs/blob/main/demo.md

Clones the Neon Auth Demo App repository from GitHub to set up the project.

```bash
git clone https://github.com/neondatabase-labs/neon-auth-demo-app.git
```

--------------------------------

### ServerTeam Get Team Profile

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/types/server-team.md

Fetches the team profile for a specified user.

```typescript
declare function getTeamProfile(user: ServerUser): Promise<EditableTeamMemberProfile>;
// Parameters:
// - user: The user object.
// Returns: Promise<EditableTeamMemberProfile>
```

--------------------------------

### Generate SDK Keys

Source: https://github.com/curtis-arch/neon-docs/blob/main/api.md

Generates SDK keys for your auth provider integration. These keys are used to set up your frontend and backend SDKs. Requires project_id and auth_provider.

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/projects/auth/keys' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '{ \
       "project_id": "project-id", \
       "auth_provider": "stack" \
     }' | jq
```

--------------------------------

### Use Team

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/objects/stack-server-app.md

Gets a team by its ID. This function is used to access a specific team within the project.

```typescript
const team = stackServerApp.useTeam('team_id');
```

--------------------------------

### Neon Auth Components

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Discover the available components for building applications with Neon Auth.

```react
See /docs/neon-auth/components/components
```

--------------------------------

### Onboarding Page Implementation (React/Next.js)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/user-onboarding.md

This snippet demonstrates a basic React component for an onboarding page. It uses state to manage user input for an address and updates the user's client metadata with an 'onboarded' flag and the provided address upon submission. It relies on the `useUser` hook from '@stackframe/stack' and `useRouter` from 'next/navigation'.

```jsx
export default function OnboardingPage() {
  const user = useUser();
  const router = useRouter();
  const [address, setAddress] = useState('');


  return <>
    <input
      type="text"
      value={address}
      onChange={(e) => setAddress(e.target.value)}
    />

    <button onClick={async () => {
      await user.update({
        clientMetadata: {
          onboarded: true,
          address,
        },
      });
      router.push('/');
    }}>
      Submit
    </button>
    </>
  );
}
```

--------------------------------

### ServerTeam Get Permission

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/types/server-team.md

Retrieves a specific permission for the team within a given scope, with options for handling missing permissions.

```typescript
declare function getPermission(
  scope: string,
  permissionId: string,
  options?: {
    or?: 'return-null' | 'throw';
  }
): Promise<TeamPermission | null>;
// Parameters:
// - scope: The scope of the permission.
// - permissionId: The ID of the permission.
// - options: Configuration for handling missing permissions ('return-null' or 'throw').
// Returns: Promise<TeamPermission | null>
```

--------------------------------

### Create User

Source: https://github.com/curtis-arch/neon-docs/blob/main/api.md

Creates a new user in your auth provider's system. Requires project_id, auth_provider, and email. Optionally accepts a name.

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/projects/auth/user' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '{ \
       "project_id": "project-id", \
       "auth_provider": "stack", \
       "email": "user@example.com", \
       "name": "Example User" \
     }' | jq
```

--------------------------------

### Next.js Demo App

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Explore the open-source Next.js demo application showcasing Neon Auth.

```github
See https://github.com/neondatabase-labs/neon-auth-demo-app
```

--------------------------------

### Neon Auth How it Works

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Understand the mechanisms behind Neon Auth's real-time user data synchronization with your database.

```sql
See /docs/guides/neon-auth-how-it-works
```

--------------------------------

### Restore Branch using Neon CLI

Source: https://github.com/curtis-arch/neon-docs/blob/main/demo.md

Restores a specific branch to a previous state. This is useful for cleaning up orphaned data before applying constraints. Requires the Neon CLI to be installed.

```bash
> neon branches restore production ^self@<timestamp> --preserve-under-name production_backup
>
```

--------------------------------

### Project Configuration Properties

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/types/project.md

Details the configuration settings for the project, including enabled features like sign-up, authentication methods, and client-side operations.

```typescript
declare const config: {
  signUpEnabled: boolean;
  credentialEnabled: boolean;
  magicLinkEnabled: boolean;
  clientTeamCreationEnabled: boolean;
  clientUserDeletionEnabled: boolean;
};
```

--------------------------------

### Leave a Team

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/orgs-and-teams.md

Allows any user to leave a team without requiring specific permissions. It involves first getting the team and then calling the `leaveTeam` function on the `User` object.

```tsx
const team = await user.getTeam('some-team-id');
await user.leaveTeam(team);
```

--------------------------------

### Vanilla TS Template

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

A template for vanilla TypeScript projects integrating Neon Auth.

```github
See https://github.com/neondatabase-labs/neon-auth-ts-template
```

--------------------------------

### Get Current User's Team Profile (Client)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/orgs-and-teams.md

Retrieves the current user's team profile using the `useTeamProfile` function on the `User` object. This is a client-side operation.

```tsx
const teamProfile = user.useTeamProfile(team);
```

--------------------------------

### StackApp Fetching vs. Hooks

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/stack-app.md

Demonstrates the difference between asynchronous fetching functions (getXyz/listXyz) that return Promises and React hooks (useXyz) that suspend until data is available. Suitable for server and client components.

```tsx
// server-component.tsx
async function ServerComponent() {
  const app = stackServerApp;
  // returns a Promise, must be awaited
  const user = await app.getUser();

  return <div>{user.displayName}</div>;
}

// client-component.tsx
('use client');
function ClientComponent() {
  const app = useStackApp();
  // returns the value directly
  const user = app.useUser();

  return <div>{user.displayName}</div>;
}
```

--------------------------------

### Get Current User's Team Profile (Server)

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/orgs-and-teams.md

Retrieves the current user's team profile using the `getTeamProfile` function on the `User` object. This is a server-side operation.

```tsx
const teamProfile = await user.getTeamProfile(team);
```

--------------------------------

### Update User Display Name

Source: https://github.com/curtis-arch/neon-docs/blob/main/get-started/accessing-user-data.md

Shows how to update a user's display name using the `user.update()` function in a client component. This functionality is available if your white-labeled setup permits it.

```tsx
'use client';
import { useUser } from '@stackframe/stack';

export default function MyClientComponent() {
  const user = useUser();
  return (
    <button onClick={async () => await user.update({ displayName: 'New Name' })}>
      Change Name
    </button>
  );
}
```

--------------------------------

### Neon Auth API Reference - Create Users

Source: https://github.com/curtis-arch/neon-docs/blob/main/create-users.md

API documentation for creating users in Neon Auth. This section details the endpoint, request method, headers, and data payload required to create a new user.

```APIDOC
POST /api/v2/projects/auth/user

Description:
  Creates a new user in Neon Auth.

Request Headers:
  - authorization: Bearer $NEON_API_KEY
  - content-type: application/json

Request Body:
  {
    "project_id": "string",       // Required. The ID of the Neon project.
    "auth_provider": "string",    // Required. The authentication provider (e.g., 'stack').
    "email": "string",          // Required. The email address of the user.
    "name": "string"            // Required. The name of the user.
  }

Response:
  (Details of the response body would typically be here, e.g., user object or success message)

Related:
  - Neon Auth API Reference: /docs/guides/neon-auth-api
```

--------------------------------

### Neon Auth Email Server Configuration

Source: https://github.com/curtis-arch/neon-docs/blob/main/best-practices.md

Configuration options for Neon Auth's email server settings.

```APIDOC
Email Server Settings:
  Default (Development):
    Provider: Shared
    Sender Email: noreply@stackframe.co

  Custom (Production):
    Provider: Custom SMTP server
    Configuration: Requires user-provided SMTP server details (host, port, username, password, etc.)
    Note: Recommended for production to ensure user trust.
```

--------------------------------

### Color Mode Switcher Component

Source: https://github.com/curtis-arch/neon-docs/blob/main/customization/dark-mode.md

A client-side React component that allows users to toggle between light and dark modes. It utilizes the `useTheme` hook from next-themes to get the current theme and update it.

```jsx
'use client';
import { useTheme } from 'next-themes';

export default function ColorModeSwitcher() {
  const { theme, setTheme } = useTheme();

  return (
    <button
      onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
      aria-label="Toggle dark mode"
    >
      {theme === 'light' ? 'Switch to dark mode' : 'Switch to light mode'}
    </button>
  );
}
```

--------------------------------

### Manage OAuth Providers via API

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/oauth.md

Provides detailed documentation and examples for managing OAuth providers programmatically using the Neon Auth API. This includes endpoints for adding, updating, and removing providers.

```APIDOC
Manage OAuth Providers via API:

This section details the API endpoints for managing OAuth providers.

**Endpoints:**

*   **Add OAuth Provider:**
    *   **Method:** POST
    *   **Path:** `/oauth/providers`
    *   **Request Body:**
        ```json
        {
          "name": "string",
          "client_id": "string",
          "client_secret": "string",
          "redirect_uri": "string",
          "scopes": ["string"]
        }
        ```
    *   **Description:** Adds a new OAuth provider configuration.
    *   **Parameters:**
        *   `name` (string, required): The name of the OAuth provider (e.g., 'google', 'github').
        *   `client_id` (string, required): The client ID obtained from the OAuth provider.
        *   `client_secret` (string, required): The client secret obtained from the OAuth provider.
        *   `redirect_uri` (string, required): The redirect URI registered with the OAuth provider.
        *   `scopes` (array of strings, optional): The OAuth scopes to request.
    *   **Returns:** The created OAuth provider object.

*   **Get OAuth Providers:**
    *   **Method:** GET
    *   **Path:** `/oauth/providers`
    *   **Description:** Retrieves a list of all configured OAuth providers.
    *   **Returns:** An array of OAuth provider objects.

*   **Get OAuth Provider by ID:**
    *   **Method:** GET
    *   **Path:** `/oauth/providers/{providerId}`
    *   **Description:** Retrieves a specific OAuth provider by its ID.
    *   **Parameters:**
        *   `providerId` (string, required): The unique identifier of the OAuth provider.
    *   **Returns:** The requested OAuth provider object.

*   **Update OAuth Provider:**
    *   **Method:** PUT
    *   **Path:** `/oauth/providers/{providerId}`
    *   **Request Body:** (Same structure as POST request body, fields are optional for partial updates)
    *   **Description:** Updates an existing OAuth provider configuration.
    *   **Parameters:**
        *   `providerId` (string, required): The unique identifier of the OAuth provider to update.
    *   **Returns:** The updated OAuth provider object.

*   **Delete OAuth Provider:**
    *   **Method:** DELETE
    *   **Path:** `/oauth/providers/{providerId}`
    *   **Description:** Removes an OAuth provider configuration.
    *   **Parameters:**
        *   `providerId` (string, required): The unique identifier of the OAuth provider to delete.
    *   **Returns:** A success message or status code indicating deletion.

**Error Conditions:**
*   Invalid input data (e.g., missing required fields, incorrect data types).
*   Provider ID not found for update or delete operations.
*   Authentication or authorization errors.
```

--------------------------------

### Neon Auth Environment Variables for React (Vite)

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/react.md

Lists the necessary environment variables for Neon Auth in a React (Vite) project, including project ID, publishable key, secret key, and database URL.

```bash
# 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
```

--------------------------------

### SignUp Component Props

Source: https://github.com/curtis-arch/neon-docs/blob/main/components/sign-up.md

Defines the available props for the Neon Auth SignUp component. Includes optional boolean flags for page rendering and input fields, a node for extra information, and an enum for the initial tab.

```APIDOC
SignUp Component Props:

- fullPage (optional): boolean — If true, renders the sign-up page in full-page mode.
- automaticRedirect (optional): boolean — If true, redirects to afterSignIn/afterSignUp URL when user is already signed in without showing the 'You are signed in' message.
- noPasswordRepeat (optional): boolean — If true, removes the password confirmation field.
- extraInfo (optional): React.ReactNode — Additional information to display on the sign-up page.
- firstTab (optional): 'magic-link' | 'password' — Determines which tab is initially active. Defaults to 'magic-link' if not specified.
```

--------------------------------

### Teams List Page for Navigation

Source: https://github.com/curtis-arch/neon-docs/blob/main/concepts/team-selection.md

Example of a Next.js page that lists all available teams and provides buttons to navigate to individual team pages using deep links. It also shows a button to navigate to the most recently selected team.

```tsx
'use client';

import { useRouter } from 'next/navigation';
import { useUser } from '@stackframe/stack';

export default function TeamsPage() {
  const user = useUser({ or: 'redirect' });
  const teams = user.useTeams();
  const router = useRouter();
  const selectedTeam = user.selectedTeam;

  return (
    <div>
      {selectedTeam && (
        <button onClick={() => router.push(`/team/${selectedTeam.id}`)}>Most recent team</button>
      )}

      <h2>All Teams</h2>
      {teams.map((team) => (
        <button key={team.id} onClick={() => router.push(`/team/${team.id}`)}>
          Open {team.displayName}
        </button>
      ))}
    </div>
  );
}
```

--------------------------------

### React SDK API Reference

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Comprehensive API reference for the React SDK used with Neon Auth.

```react
See /docs/neon-auth/sdk/react/overview
```

--------------------------------

### Custom Sign-In Page with Pre-built Component

Source: https://github.com/curtis-arch/neon-docs/blob/main/customization/custom-pages.md

Demonstrates creating a custom sign-in page by wrapping the pre-built `SignIn` component from '@stackframe/stack'. This approach allows for UI customization while leveraging existing authentication logic.

```tsx
import { SignIn } from '@stackframe/stack';

export default function CustomSignInPage() {
  return (
    <div>
      <h1>My Custom Sign In page</h1>
      <SignIn />
    </div>
  );
}
```

--------------------------------

### Get Neon Project Email Server Configuration

Source: https://github.com/curtis-arch/neon-docs/blob/main/api.md

Retrieves the email server configuration for a specified Neon project. Requires the project ID. The configuration typically indicates the type of email server used (e.g., 'shared').

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/auth/email_server' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' | jq
```

```json
{
  "type": "shared"
}
```

--------------------------------

### Neon Auth RLS Configuration

Source: https://github.com/curtis-arch/neon-docs/blob/main/best-practices.md

Steps to enable Row-Level Security (RLS) in Neon by integrating with Neon Auth. This involves copying the JWKS URL from Neon Auth and configuring it in Neon project settings, along with installing extensions and setting up roles.

```APIDOC
Neon Auth RLS Integration:

1. Obtain JWKS URL:
   - Navigate to the **Configuration** tab in your Neon Auth project.
   - Copy the **JWKS URL** from the **Claim project** section.

2. Configure Neon Project:
   - In your Neon project, go to **Settings > RLS**.
   - Paste the copied JWKS URL.

3. Database Setup:
   - Install the `pg_session_jwt` extension.
   - Set up `authenticated` and `anonymous` roles.
   - Implement RLS policies on your tables.

   Refer to the [Stack Auth + Neon RLS guide](/docs/guides/neon-rls-stack-auth) for detailed steps from step 3 onwards.
```

--------------------------------

### Run Test Script

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/javascript.md

Provides commands to run the test script for Neon Auth integration, either via a package.json script or directly using dotenv and tsx.

```bash
# if you have a dev/test script in package.json

npm run dev

# or directly:

npx dotenv -e .env.local -- tsx src/test.ts
```

--------------------------------

### Create Neon Auth Integration

Source: https://github.com/curtis-arch/neon-docs/blob/main/api.md

Creates a Neon-managed authentication project for your database, provisioning and configuring a new auth provider project. Requires project ID, branch ID, database name, and role name.

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/projects/auth/create' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '{ \
       "auth_provider": "stack", \
       "project_id": "project-id", \
       "branch_id": "br-example-123", \
       "database_name": "neondb", \
       "role_name": "neondb_owner" \
     }' | jq
```

```json
{
  "auth_provider": "stack",
  "auth_provider_project_id": "proj-example-123",
  "pub_client_key": "pck_example123",
  "secret_server_key": "ssk_example123",
  "jwks_url": "https://api.stack-auth.com/api/v1/projects/proj-example-123/.well-known/jwks.json",
  "schema_name": "neon_auth",
  "table_name": "users_sync"
}
```

--------------------------------

### ThemeProvider Setup with Neon Auth

Source: https://github.com/curtis-arch/neon-docs/blob/main/customization/dark-mode.md

Configures the `ThemeProvider` from next-themes in the application's layout file (`layout.tsx`). It sets the default theme to 'system' and uses 'class' attribute for theme application, ensuring Neon Auth components (`StackTheme`) adapt to the selected theme.

```jsx
import { ThemeProvider } from 'next-themes'

export default function Layout({ children }) {
return (
    <ThemeProvider defaultTheme="system" attribute="class">
    <StackTheme>
        {children}
    </StackTheme>
    </ThemeProvider>
)
}
```

--------------------------------

### Create Team API

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/nextjs/objects/stack-server-app.md

Creates a new team with the specified display name and profile image URL. It returns a promise that resolves to the newly created ServerTeam object.

```typescript
stackServerApp.createTeam([options])
  - Creates a team.
  - Parameters:
    - options (object): Configuration for the new team.
      - displayName (string): The display name for the team.
      - profileImageUrl (string | null): The URL of the team's profile image, or null to remove.
  - Returns: Promise<ServerTeam>
  - Example:
    const team = await stackServerApp.createTeam({
      displayName: 'New Team',
      profileImageUrl: 'https://example.com/profile.jpg',
    });
```

--------------------------------

### Neon Auth Environment Variables for Next.js

Source: https://github.com/curtis-arch/neon-docs/blob/main/quick-start/nextjs.md

Sets up the necessary environment variables for Neon Auth in a Next.js project. These include project ID, publishable client key, secret server key, and the Neon database connection string.

```bash
# Neon Auth environment variables for Next.js

NEXT_PUBLIC_STACK_PROJECT_ID=YOUR_NEON_AUTH_PROJECT_ID
NEXT_PUBLIC_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
```

--------------------------------

### OAuth Callback URLs

Source: https://github.com/curtis-arch/neon-docs/blob/main/best-practices.md

Callback URLs for various OAuth providers used in Neon Auth.

```APIDOC
Google:
  Callback URL: https://api.stack-auth.com/api/v1/auth/oauth/callback/google

GitHub:
  Callback URL: https://api.stack-auth.com/api/v1/auth/oauth/callback/github

Microsoft:
  Callback URL: https://api.stack-auth.com/api/v1/auth/oauth/callback/microsoft
```

--------------------------------

### React SDK Project Configuration

Source: https://github.com/curtis-arch/neon-docs/blob/main/sdk/react/types/project.md

Configures a project to use the React SDK. This component is used to specify the SDK name for project integration.

```html
<SdkProject sdkName="React" />
```

--------------------------------

### Next.js SDK API Reference

Source: https://github.com/curtis-arch/neon-docs/blob/main/overview.md

Detailed API reference for the Next.js SDK used with Neon Auth.

```nextjs
See /docs/neon-auth/sdk/nextjs/overview
```

--------------------------------

### Accessing Synchronized User Data with SQL

Source: https://github.com/curtis-arch/neon-docs/blob/main/tutorial.md

Demonstrates how to query the `neon_auth.users_sync` table to retrieve all user information. This table is automatically managed by Neon Auth and populated with data from your authentication provider.

```SQL
SELECT * FROM neon_auth.users_sync;
```