{"id":16891,"library":"remix-auth","title":"Remix Auth","description":"remix-auth is a TypeScript-first, strategy-based authentication library designed for Remix and React Router applications. Inspired by Passport.js, it provides full server-side authentication capabilities built on the Web Fetch API, ensuring compatibility with modern web standards. The library is currently stable at version 4.2.0 and maintains an active release cadence, frequently introducing new features, bug fixes, and documentation improvements. Key differentiators include its robust TypeScript support, extensible strategy pattern (with separate npm packages for various authentication flows like Form, OAuth2, etc.), and seamless integration with Remix's server-side action and loader functions, allowing developers to implement custom authentication logic. It dropped direct React Router requirements in v4.0.0, simplifying its core and making it more adaptable.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/sergiodxa/remix-auth","tags":["javascript"],"install":[{"cmd":"npm install remix-auth","lang":"bash","label":"npm"},{"cmd":"yarn add remix-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add remix-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework for which the library provides authentication solutions.","package":"remix","optional":false},{"reason":"A common strategy used for basic form-based authentication, often a first dependency for many projects.","package":"remix-auth-form","optional":true},{"reason":"Provides session management and server utilities essential for authentication flows in Remix applications.","package":"@remix-run/node","optional":false}],"imports":[{"note":"remix-auth is ESM-only since v4.0.0. Use import statements for all modules.","wrong":"const { Authenticator } = require('remix-auth');","symbol":"Authenticator","correct":"import { Authenticator } from 'remix-auth';"},{"note":"Authentication strategies are published as separate npm packages and must be imported from their respective modules.","symbol":"FormStrategy","correct":"import { FormStrategy } from 'remix-auth-form';"},{"note":"Remix v1.15.0 and later introduced `ActionArgs`/`LoaderArgs` to replace `ActionFunction`/`LoaderFunction` for type definitions. Update types in your Remix route files.","wrong":"import type { ActionFunction } from '@remix-run/node';","symbol":"ActionArgs","correct":"import type { ActionArgs } from '@remix-run/node';"}],"quickstart":{"code":"import { Form } from '@remix-run/react';\nimport { Authenticator } from 'remix-auth';\nimport { FormStrategy } from 'remix-auth-form';\nimport { createCookieSessionStorage, redirect } from '@remix-run/node';\nimport type { ActionArgs, LoaderArgs } from '@remix-run/node';\n\n// 1. Define your User type\ninterface User { id: string; email: string; name: string; }\n\n// 2. Setup session storage\nconst sessionStorage = createCookieSessionStorage({\n  cookie: {\n    name: '__session',\n    httpOnly: true,\n    path: '/',\n    sameSite: 'lax',\n    secrets: [process.env.SESSION_SECRET ?? 's3cr3t'], // Use an environment variable for secrets\n    secure: process.env.NODE_ENV === 'production',\n  },\n});\n\n// 3. Create Authenticator instance\nexport let authenticator = new Authenticator<User>(sessionStorage);\n\n// 4. Register a strategy (e.g., FormStrategy)\nauthenticator.use(\n  new FormStrategy(async ({ form }) => {\n    let email = form.get('email') as string;\n    let password = form.get('password') as string;\n\n    // Simulate user login\n    if (email === 'test@example.com' && password === 'password') {\n      return { id: '123', email, name: 'Test User' };\n    }\n    throw new Error('Invalid credentials');\n  }),\n  'user-pass' // Name of the strategy\n);\n\n// 5. Create a Login route (app/routes/login.tsx)\nexport default function Screen() {\n  return (\n    <Form method='post'>\n      <input type='email' name='email' required placeholder='Email' />\n      <input\n        type='password'\n        name='password'\n        autoComplete='current-password'\n        required\n        placeholder='Password'\n      />\n      <button type='submit'>Sign In</button>\n    </Form>\n  );\n}\n\n// 6. Handle authentication in the action function\nexport async function action({ request }: ActionArgs) {\n  try {\n    let user = await authenticator.authenticate('user-pass', request, {\n      successRedirect: '/',\n      failureRedirect: '/login?error=true',\n    });\n    return user; // Should not reach here if redirects work\n  } catch (error) {\n    // This catch block handles redirect responses thrown by authenticate\n    // or other errors. Remix will re-throw the response.\n    throw error;\n  }\n}\n\n// 7. Example loader to check authentication\nexport async function loader({ request }: LoaderArgs) {\n  let user = await authenticator.isAuthenticated(request);\n  if (!user) {\n    throw redirect('/login');\n  }\n  return { user };\n}","lang":"typescript","description":"This quickstart demonstrates the core setup of `remix-auth` with `FormStrategy`, including session storage configuration, `Authenticator` instantiation, strategy registration, and integration into Remix `action` and `loader` functions for user login and authentication checks."},"warnings":[{"fix":"Review the official migration guide or documentation for v4.0.0 to adapt your `Authenticator` and strategy configurations. Ensure your Remix application and associated packages are up to date.","message":"Version 4.0.0 introduced significant breaking changes, including dropping direct React Router requirements and a modernization of the package setup. This likely involves updates to how `Authenticator` and strategies are initialized and configured.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refactor your codebase to use ES module import syntax (`import ... from '...'`) instead of CommonJS `require()` calls for `remix-auth` and its associated strategies.","message":"As of v4.0.0, `remix-auth` is distributed as an ESM-only package. This means CommonJS `require()` syntax will no longer work and must be replaced with ESM `import` statements.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always check the `remix-auth` version supported by each strategy package's documentation or `package.json` before installation. Install compatible versions to avoid runtime errors.","message":"Authentication strategies (e.g., `remix-auth-form`, `remix-auth-oauth2`) are separate npm packages. It is crucial to verify that the version of any strategy you install is compatible with your `remix-auth` version, as they may not be updated simultaneously.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you are using Remix v2, ensure your `remix-auth` package is at least v3.6.0. It is recommended to upgrade to the latest stable version of `remix-auth` for optimal compatibility and features.","message":"Remix v2 support was explicitly added in `remix-auth` v3.6.0. Earlier versions of `remix-auth` may not be fully compatible with Remix v2, leading to unexpected behavior or errors.","severity":"breaking","affected_versions":"<3.6.0"},{"fix":"Ensure you correctly initialize `Authenticator` with an instance of `SessionStorage` provided by `@remix-run/node` or a custom implementation. Configure session cookie options, including a secure `secrets` array, correctly.","message":"The `Authenticator` requires a `SessionStorage` instance (e.g., `createCookieSessionStorage`, `createMemorySessionStorage`) for managing user sessions. Misconfiguration or failure to provide a valid `SessionStorage` can lead to authentication failures or state loss.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update all `remix-auth` imports (and other ESM packages) in your project to use ES module syntax: `import { Authenticator } from 'remix-auth';`. Ensure your `tsconfig.json` and `package.json` are configured for ESM output if necessary.","cause":"`remix-auth` is an ES Module (ESM) but your project or a specific file is attempting to import it using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/remix-auth/dist/index.js from .../app/services/auth.server.ts not supported. Instead change the require of index.js in .../app/services/auth.server.ts to a dynamic import() which is also all of CJS module."},{"fix":"Verify that you have correctly instantiated `Authenticator` with `new Authenticator(sessionStorage)` and that the instance is correctly exported and imported where `authenticate` is called. Double-check for typos.","cause":"The `authenticator` instance was not properly initialized or exported, or the `authenticate` method is being called on a non-`Authenticator` object.","error":"TypeError: authenticator.authenticate is not a function"},{"fix":"Ensure that you have called `authenticator.use(new MyStrategy(...), 'my-strategy')` to register your strategy with the correct name before attempting to authenticate with it.","cause":"The `authenticator.authenticate()` method was called with a strategy name that has not been registered with the `authenticator.use()` method.","error":"Error: No strategy named \"my-strategy\" was found."},{"fix":"Ensure that the `request` object from your Remix `loader` or `action` function is correctly passed as the second argument to `authenticator.authenticate()` or `authenticator.isAuthenticated()`.","cause":"The `request` object passed to `authenticator.authenticate()` or `authenticator.isAuthenticated()` is `undefined` or `null`.","error":"TypeError: Cannot read properties of undefined (reading 'headers')"}],"ecosystem":"npm","meta_description":null}