MYTPEN Auth Integration Package

Common errors

• Error: ENOENT: no such file or directory, stat '/path/to/your/project/.env' OR "Environment variable MYTPEN_AUTH_SECRET is not defined."

  cause The `.env` file is missing, improperly named, or critical environment variables are not loaded/set.
  fix Create a `.env` file in your project root with all required `MYTPEN_*` and Redis variables. For deployments, ensure these variables are configured in your hosting platform's environment settings.

• TypeError: (0 , _mytpen_auth_provider__WEBPACK_IMPORTED_MODULE_2__.MytpenAuthProvider) is not a function OR "React Context Error: The `MytpenAuthProvider` was not found in the component tree."

  cause `MytpenAuthProvider` is either imported incorrectly (wrong path) or not rendered high enough in the React component tree (e.g., not in `app/layout.tsx`).
  fix Ensure `import { MytpenAuthProvider } from "mytpen-auth/provider";` is used and `MytpenAuthProvider` wraps your entire application in `app/layout.tsx`.

• Error: OIDC provider configuration missing or invalid. Check MYTPEN_PROVIDER_ID, MYTPEN_CLIENT_ID, MYTPEN_CLIENT_SECRET.

  cause One or more required OIDC environment variables are missing or contain incorrect values.
  fix Double-check `MYTPEN_PROVIDER_ID`, `MYTPEN_CLIENT_ID`, and `MYTPEN_CLIENT_SECRET` in your `.env` file or deployment environment against the values from your MYTPEN dashboard.

• Error: Could not connect to Upstash Redis. Check UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

  cause The Upstash Redis REST API URL or token is incorrect, expired, or a network issue is preventing connection to the Redis instance.
  fix Verify `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` in your `.env` file against your Upstash console. Confirm they correspond to the REST API endpoint.

Warnings

• gotcha Incorrect or incomplete environment variables are the leading cause of setup failures. Crucial variables include `MYTPEN_AUTH_SECRET`, OIDC credentials (`MYTPEN_PROVIDER_ID`, `MYTPEN_CLIENT_ID`, `MYTPEN_CLIENT_SECRET`), callback URLs (`MYTPEN_AUTH_BASEURL`), and Redis credentials (`UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN`).
  Fix: Thoroughly review Step 4 of the `mytpen-auth` setup guide. Ensure all required `MYTPEN_*` variables are precisely copied from the MYTPEN dashboard and Redis credentials from Upstash. Verify `MYTPEN_AUTH_BASEURL` accurately reflects your application's public URL and port.
• gotcha `MytpenAuthProvider` is designed to be a server component and must be placed within Next.js `app/layout.tsx`. Attempting to use it in a client component or in a file that is not a server component will result in React errors or context not being available.
  Fix: Ensure `MytpenAuthProvider` is rendered directly in your `app/layout.tsx` file, which is a server component by default in the Next.js App Router. If client-side interactivity is needed, wrap your client components *inside* the `MytpenAuthProvider`.
• gotcha The package strongly recommends using the *same Redis instance* (e.g., Upstash) as the MYTPEN dashboard for its secondary storage. Mismatching or misconfiguring the Redis connection can lead to inconsistencies in session data, authentication issues, or stale states, particularly in production environments.
  Fix: Follow Step 3 of the setup guide to configure Upstash Redis REST API credentials (`UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN`). If your hosting platform uses different variable names (e.g., Vercel's `KV_REST_API_URL`), ensure they are correctly mapped.
• gotcha Certain components and utilities, such as `MytpenAuthProvider` and `getCurrentPathname`, require specific subpath imports (e.g., `mytpen-auth/provider`, `mytpen-auth/nextjs`). Importing them directly from the root `mytpen-auth` package path will result in module resolution errors or undefined exports.
  Fix: Always refer to the official documentation or quickstart examples for the correct and precise import paths. Use `import { Symbol } from 'mytpen-auth/subpath';` as specified.

Install

• npm install mytpen-auth npm
• yarn add mytpen-auth yarn
• pnpm add mytpen-auth pnpm

Imports

• auth
  wrong:

  const { auth } = require('mytpen-auth');

  correct:

  import { auth } from 'mytpen-auth';

  This package is primarily designed for ESM. `auth` is the core server-side authentication handler.
• toNextJsHandler
  wrong:

  const { toNextJsHandler } = require('mytpen-auth');

  correct:

  import { toNextJsHandler } from 'mytpen-auth';

  Used to adapt the `auth` handler for Next.js API routes, converting it into a compatible `GET`/`POST` handler.
• MytpenAuthProvider
  wrong:

  import { MytpenAuthProvider } from 'mytpen-auth';

  correct:

  import { MytpenAuthProvider } from 'mytpen-auth/provider';

  This React context provider must be imported from the specific subpath `mytpen-auth/provider` and is intended for use as a server component in Next.js `app/layout.tsx`.
• getCurrentPathname
  wrong:

  import { getCurrentPathname } from 'mytpen-auth';

  correct:

  import { getCurrentPathname } from 'mytpen-auth/nextjs';

  A utility function specifically for Next.js environments, requiring import from the `mytpen-auth/nextjs` subpath.

Quickstart

This quickstart demonstrates the essential configuration for `mytpen-auth` within a Next.js `app` directory project. It includes setting up the API route handler, integrating `MytpenAuthProvider` into the root layout, and highlights the critical environment variables required for successful authentication and Redis integration.

    // In your .env file (or configured in deployment environment):
    // MYTPEN_AUTH_SECRET="your-strong-random-secret-key"
    // MYTPEN_PROVIDER_ID="your-app-id-from-dashboard"
    // MYTPEN_CLIENT_ID="your-client-id-from-dashboard"
    // MYTPEN_CLIENT_SECRET="your-client-secret-from-dashboard"
    // MYTPEN_AUTH_SERVER="https://dashboard.mytpen.app" (or your IdP origin)
    // MYTPEN_AUTH_BASEURL="http://localhost:3000" (or your app's base URL for callbacks)
    // UPSTASH_REDIS_REST_URL="https://your-instance.upstash.io"
    // UPSTASH_REDIS_REST_TOKEN="your-upstash-rest-token"

    // app/api/auth/[...all]/route.ts
    import { auth, toNextJsHandler } from "mytpen-auth";

    // Export GET and POST handlers for the Next.js API route
    export const { GET, POST } = toNextJsHandler(auth);

    // app/layout.tsx
    import { MytpenAuthProvider } from "mytpen-auth/provider";
    import { LogoSvg } from "mytpen-auth/components"; // Example component (optional)
    import { getCurrentPathname } from "mytpen-auth/nextjs"; // Example utility (optional)
    import "./globals.css"; // Assuming you have global styles

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      const pathname = getCurrentPathname(); // Example usage of a utility

      return (
        <html lang="en">
          <body>
            <MytpenAuthProvider>
              <header style={{ display: 'flex', justifyContent: 'space-between', padding: '1rem', borderBottom: '1px solid #eee' }}>
                <LogoSvg width={100} height={30} />
                <nav>
                  <a href="/dashboard" style={{ margin: '0 0.5rem' }}>Dashboard</a>
                  <a href="/profile" style={{ margin: '0 0.5rem' }}>Profile</a>
                  <a href="/api/auth/signout" style={{ margin: '0 0.5rem' }}>Sign Out</a>
                </nav>
              </header>
              <main style={{ minHeight: '80vh', padding: '2rem' }}>
                {children}
              </main>
              <footer style={{ marginTop: '2rem', textAlign: 'center', color: '#888' }}>
                <p>Application Footer - Current Path: {pathname}</p>
              </footer>
            </MytpenAuthProvider>
          </body>
        </html>
      );
    }