Remix Auth Facebook Strategy

Common errors

• Error: FacebookStrategy requires a clientID, clientSecret and callbackURL.

  cause One or more required configuration options (clientID, clientSecret, callbackURL) for the FacebookStrategy were not provided during its instantiation.
  fix Ensure `FACEBOOK_CLIENT_ID`, `FACEBOOK_CLIENT_SECRET`, and `FACEBOOK_CALLBACK_URL` environment variables are correctly set and accessible to your Remix application when initializing `FacebookStrategy`.

• Error: OAuth2Strategy requires a `verify` function.

  cause The `FacebookStrategy` (which extends `OAuth2Strategy`) was instantiated without providing a `verify` callback function as its second argument.
  fix Add an asynchronous `verify` function as the second argument to `new FacebookStrategy(...)`. This function receives the `profile` and other data from Facebook and is responsible for finding or creating a user in your database and returning a user object for the session.

• The redirect_uri URL must be an absolute URL

  cause The `callbackURL` provided to `FacebookStrategy` is not a complete, absolute URL (e.g., missing 'https://' or the full domain).
  fix Ensure your `FACEBOOK_CALLBACK_URL` environment variable, or the `callbackURL` string directly, is a fully qualified URL including the protocol (e.g., `https://yourdomain.com/auth/facebook/callback`).

Warnings

• gotcha The `callbackURL` configured in the FacebookStrategy must exactly match one of the 'Valid OAuth Redirect URIs' configured in your Facebook App settings. A mismatch will cause Facebook to reject the authentication attempt.
  Fix: Verify that the `callbackURL` passed to `FacebookStrategy` is identical to an entry in your Facebook App's 'Basic Settings' -> 'Products' -> 'Facebook Login' -> 'Settings' -> 'Valid OAuth Redirect URIs'. Include protocol (http/https), hostname, port, and path.
• gotcha All sensitive credentials (like `FACEBOOK_CLIENT_ID`, `FACEBOOK_CLIENT_SECRET`, and `SESSION_SECRET`) must be stored as environment variables and never hardcoded in your application.
  Fix: Use environment variables (e.g., `.env` file, server configuration) for all secrets. Access them via `process.env.VAR_NAME` and provide fallback values or strict validation.
• gotcha Remix Auth strategies, including `FacebookStrategy`, typically run on the server. Do not attempt to import or use these strategies in client-side code, as it can expose secrets or lead to runtime errors.
  Fix: Ensure `auth.server.ts` or similar server-only files containing `Authenticator` and strategy configurations are only imported in Remix `loader` or `action` functions, or other server-side contexts (`.server.ts` files).
• breaking The v1.0.0 release introduced 'better typing and extensibility'. While no explicit breaking changes for typical usage were documented, custom implementations or reliance on internal types might require adjustments.
  Fix: Review your `verify` callback function and any custom types extending `FacebookStrategy` or related `remix-auth` interfaces when upgrading to v1.0.0 or later to ensure compatibility with updated typings. Test thoroughly.

Install

• npm install remix-auth-facebook npm
• yarn add remix-auth-facebook yarn
• pnpm add remix-auth-facebook pnpm

Imports

• FacebookStrategy
  wrong:

  const FacebookStrategy = require('remix-auth-facebook');

  correct:

  import { FacebookStrategy } from 'remix-auth-facebook';

  Remix projects are primarily ESM. CommonJS 'require' syntax is not officially supported and may lead to module resolution issues.
• Authenticator
  wrong:

  import Authenticator from 'remix-auth';

  correct:

  import { Authenticator } from 'remix-auth';

  Authenticator is a named export from the parent `remix-auth` library, not a default export.
• Profile

  import type { Profile } from 'remix-auth';

  The `Profile` type, representing the authenticated user's profile data, is exported from `remix-auth` and is useful for typing the `verify` callback function.

Quickstart

This quickstart demonstrates how to initialize `remix-auth` with `FacebookStrategy`, define a user type, and configure the session storage using environment variables.

import { Authenticator } from 'remix-auth';
import { FacebookStrategy } from 'remix-auth-facebook';
import { createCookieSessionStorage } from '@remix-run/node';

// 1. Create a session storage (e.g., cookie based)
//    Ensure SESSION_SECRET is set in your .env
export const sessionStorage = createCookieSessionStorage({
  cookie: {
    name: '__session',
    httpOnly: true,
    path: '/',
    sameSite: 'lax',
    secrets: [process.env.SESSION_SECRET ?? 's3cr3t'],
    secure: process.env.NODE_ENV === 'production',
  },
});

// 2. Create an Authenticator instance
//    Replace `User` with your actual user type
export type User = { id: string; name: string; email: string; };
export const authenticator = new Authenticator<User>(sessionStorage);

// 3. Configure the Facebook Strategy
//    Ensure FACEBOOK_CLIENT_ID, FACEBOOK_CLIENT_SECRET, and FACEBOOK_CALLBACK_URL are set in your .env
authenticator.use(
  new FacebookStrategy(
    {
      clientID: process.env.FACEBOOK_CLIENT_ID ?? '',
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET ?? '',
      callbackURL: process.env.FACEBOOK_CALLBACK_URL ?? 'http://localhost:3000/auth/facebook/callback',
    },
    async ({ profile }) => {
      // This is where you find or create the user in your database
      // using the profile data provided by Facebook.
      // For demonstration, we'll just return a mock user.
      return {
        id: profile.id,
        name: profile.displayName,
        email: profile.emails?.[0]?.value || `${profile.id}@example.com`,
      };
    }
  ),
  'facebook' // Name of the strategy
);

// Example routes (in app/routes/auth/facebook.tsx and app/routes/auth/facebook/callback.tsx)
// app/routes/auth/facebook.tsx (for initiating login)
// export async function loader({ request }: LoaderFunction) {
//   return authenticator.authenticate('facebook', request);
// }

// app/routes/auth/facebook/callback.tsx (for handling the callback)
// export async function loader({ request }: LoaderFunction) {
//   return authenticator.authenticate('facebook', request, {
//     successRedirect: '/dashboard',
//     failureRedirect: '/login',
//   });
// }