{"id":18321074,"url":"https://github.com/workos/authkit-remix","last_synced_at":"2025-04-10T01:06:41.411Z","repository":{"id":244434350,"uuid":"814689557","full_name":"workos/authkit-remix","owner":"workos","description":"Authentication and session helpers for using WorkOS \u0026 AuthKit with Remix","archived":false,"fork":false,"pushed_at":"2025-04-08T20:22:29.000Z","size":358,"stargazers_count":26,"open_issues_count":9,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-10T01:06:36.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-13T13:57:11.000Z","updated_at":"2025-04-08T20:20:54.000Z","dependencies_parsed_at":"2024-07-15T17:21:37.984Z","dependency_job_id":"c7ea378f-4aaf-4857-8c79-a852ce1599c0","html_url":"https://github.com/workos/authkit-remix","commit_stats":null,"previous_names":["workos/authkit-remix"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fauthkit-remix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fauthkit-remix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fauthkit-remix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fauthkit-remix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workos","download_url":"https://codeload.github.com/workos/authkit-remix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:18:16.694Z","updated_at":"2025-04-10T01:06:41.393Z","avatar_url":"https://github.com/workos.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AuthKit Remix Library\n\nThe AuthKit library for Remix provides convenient helpers for authentication and session management using WorkOS \u0026 AuthKit with Remix. You can find this library in action in the [remix-authkit-example](https://github.com/workos/remix-authkit-example) repo.\n\n## Installation\n\nInstall the package with:\n\n```\nnpm i @workos-inc/authkit-remix\n```\n\nor\n\n```\nyarn add @workos-inc/authkit-remix\n```\n\n## Configuration\n\nAuthKit for Remix offers a flexible configuration system that allows you to customize various settings. You can configure the library in three ways:\n\n### 1. Environment Variables\n\n  The simplest way is to set environment variables in your `.env.local` file:\n\n  ```bash\n  WORKOS_CLIENT_ID=\"client_...\" # retrieved from the WorkOS dashboard\n  WORKOS_API_KEY=\"sk_test_...\" # retrieved from the WorkOS dashboard\n  WORKOS_REDIRECT_URI=\"http://localhost:5173/callback\" # configured in the WorkOS dashboard\n  WORKOS_COOKIE_PASSWORD=\"\u003cyour password\u003e\" # generate a secure password here\n```\n\n### 2. Programmatic Configuration\n\nYou can also configure AuthKit programmatically by importing the `configure` function:\n\n```typescript\nimport { configure } from '@workos-inc/authkit-remix';\n// In your root or entry file\nconfigure({\n  clientId: 'client_1234567890',\n  apiKey: 'sk_test_1234567890',\n  redirectUri: 'http://localhost:5173/callback',\n  cookiePassword: 'your-secure-cookie-password',\n  // Optional settings\n  cookieName: 'my-custom-cookie-name',\n  apiHttps: true,\n  cookieMaxAge: 60 * 60 * 24 * 30, // 30 days\n});\n```\n\n### 3. Custom Environment Source\n\nFor non-standard environments (like Deno or Edge functions), you can provide a custom environment variable source:\n\n\u003e [!Warning]\n\u003e\n\u003eWhile this library includes support for custom environment sources that could theoretically work in non-Node.js runtimes like Deno or Edge functions, this functionality has not been extensively tested (yet). If you're planning to use AuthKit in these environments, you may encounter unexpected issues. We welcome feedback and contributions from users who test in these environments.\n\n```typescript\nimport { configure } from '@workos-inc/authkit-remix';\n\nconfigure(key =\u003e Deno.env.get(key));\n// Or combine with explicit values\nconfigure(\n  { clientId: 'client_1234567890' },\n  key =\u003e Deno.env.get(key)\n);\n```\n\n### Configuration Priority\n\nWhen retrieving configuration values, AuthKit follows this priority order:\n\n1. Programmatically provided values via `configure()`\n2. Environment variables (prefixed with `WORKOS_`)\n3. Default values for optional settings\n\n### Available Configuration Options\n\n\u003e[!NOTE]\n\u003e\n\u003eTo print out the entire config, a `getFullConfig` function is provided for debugging purposes.\n\n|  Option |  Environment Variable |  Default |  Required |  Description |  \n| ---- | ---- | ---- | ---- | ----  |\n|  `clientId` |  `WORKOS_CLIENT_ID` |  - |  Yes |  Your WorkOS Client ID |  \n|  `apiKey` |  `WORKOS_API_KEY` |  - |  Yes |  Your WorkOS API Key |  \n|  `redirectUri` |  `WORKOS_REDIRECT_URI` |  - |  Yes |  The callback URL configured in WorkOS |  \n|  `cookiePassword` |  `WORKOS_COOKIE_PASSWORD` |  - |  Yes |  Password for cookie encryption (min 32 chars) |  \n|  `cookieName` |  `WORKOS_COOKIE_NAME` |  `wos-session` |  No |  Name of the session cookie |  \n|  `apiHttps` |  `WORKOS_API_HTTPS` |  `true` |  No |  Whether to use HTTPS for API calls |  \n|  `cookieMaxAge` |  `WORKOS_COOKIE_MAX_AGE` |  `34560000` (400 days) |  No |  Maximum age of cookie in seconds |  \n|  `apiHostname` |  `WORKOS_API_HOSTNAME` |  `api.workos.com` |  No |  WorkOS API hostname |  \n|  `apiPort` |  `WORKOS_API_PORT` |  - |  No |  Port to use for API calls | \n\n\u003e[!NOTE]\n\u003e\n\u003eThe `cookiePassword` must be at least 32 characters long for security reasons.\n\n## Setup\n\n### Callback route\n\nAuthKit requires that you have a callback URL to redirect users back to after they've authenticated. In your Remix app, [create a new route](https://remix.run/docs/en/main/discussion/routes) and add the following:\n\n```ts\nimport { authLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = authLoader();\n```\n\nMake sure this route matches the `WORKOS_REDIRECT_URI` variable and the configured redirect URI in your WorkOS dashboard. For instance if your redirect URI is `http://localhost:2884/callback` then you'd put the above code in `/app/routes/callback.ts`.\n\nYou can also control the pathname the user will be sent to after signing-in by passing a `returnPathname` option to `authLoader` like so:\n\n```ts\nexport const loader = authLoader({ returnPathname: '/dashboard' });\n```\n\nIf your application needs to persist `oauthTokens` or other auth-related information after the callback is successful, you can pass an `onSuccess` option:\n\n```ts\nexport const loader = authLoader({\n  onSuccess: async ({ oauthTokens }) =\u003e {\n    await saveToDatabase(oauthTokens);\n  },\n});\n```\n\n## Usage\n\n### Access authentication data in your Remix application\n\nUse `authkitLoader` to configure AuthKit for your Remix application routes.\n\n```tsx\nimport type { LoaderFunctionArgs } from '@remix-run/node';\nimport { useLoaderData } from '@remix-run/react';\nimport { authkitLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = (args: LoaderFunctionArgs) =\u003e authkitLoader(args);\n\nexport function App() {\n  // Retrieves the user from the session or returns `null` if no user is signed in\n  // Other supported values include `sessionId`, `accessToken`, `organizationId`,\n  // `role`, `permissions`, `entitlements`, and `impersonator`.\n  const { user, signInUrl, signUpUrl } = useLoaderData\u003ctypeof loader\u003e();\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eWelcome back {user?.firstName \u0026\u0026 `, ${user?.firstName}`}\u003c/p\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nFor pages where you want to display a signed-in and signed-out view, use `authkitLoader` to retrieve the user profile from WorkOS. You can pass in additional data by providing a loader function directly to `authkitLoader`.\n\n```tsx\nimport type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';\nimport { Form, Link, useLoaderData } from '@remix-run/react';\nimport { getSignInUrl, getSignUpUrl, signOut, authkitLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = (args: LoaderFunctionArgs) =\u003e\n  authkitLoader(args, async ({ request, auth }) =\u003e {\n    return {\n      signInUrl: await getSignInUrl(),\n      signUpUrl: await getSignUpUrl(),\n    };\n  });\n\nexport async function action({ request }: ActionFunctionArgs) {\n  return await signOut(request);\n}\n\nexport default function HomePage() {\n  const { user, signInUrl, signUpUrl } = useLoaderData\u003ctypeof loader\u003e();\n\n  if (!user) {\n    return (\n      \u003c\u003e\n        \u003cLink to={signInUrl}\u003eLog in\u003c/Link\u003e\n        \u003cbr /\u003e\n        \u003cLink to={signUpUrl}\u003eSign Up\u003c/Link\u003e\n      \u003c/\u003e\n    );\n  }\n\n  return (\n    \u003cForm method=\"post\"\u003e\n      \u003cp\u003eWelcome back {user?.firstName \u0026\u0026 `, ${user?.firstName}`}\u003c/p\u003e\n      \u003cbutton type=\"submit\"\u003eSign out\u003c/button\u003e\n    \u003c/Form\u003e\n  );\n}\n```\n\n### Requiring auth\n\nFor pages where a signed-in user is mandatory, you can use the `ensureSignedIn` option:\n\n```tsx\nexport const loader = (args: LoaderFunctionArgs) =\u003e authkitLoader(args, { ensureSignedIn: true });\n```\n\nEnabling `ensureSignedIn` will redirect users to AuthKit if they attempt to access the page without being authenticated.\n\n### Signing out\n\nUse the `signOut` method to sign out the current logged in user, end the session, and redirect to your app's homepage. The homepage redirect is set in your WorkOS dashboard settings under \"Redirect\".\n\n### Get the access token\n\nSometimes it is useful to obtain the access token directly, for instance to make API requests to another service.\n\n```tsx\nimport type { LoaderFunctionArgs } from '@remix-run/node';\nimport { authkitLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = (args: LoaderFunctionArgs) =\u003e\n  authkitLoader(args, async ({ auth }) =\u003e {\n    const { accessToken } = auth;\n\n    if (!accessToken) {\n      // Not signed in\n    }\n\n    const serviceData = await fetch('/api/path', {\n      headers: {\n        Authorization: `Bearer ${accessToken}`,\n      },\n    });\n\n    return {\n      data: serviceData,\n    };\n  });\n```\n\n### Debugging\n\nTo enable debug logs, pass in the debug flag when using `authkitLoader`.\n\n```ts\nimport { authkitLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = (args: LoaderFunctionArgs) =\u003e authkitLoader(args, { debug: true });\n```\n\nIf providing a loader function, you can pass the options object as the third parameter\n\n```ts\nimport { authkitLoader } from '@workos-inc/authkit-remix';\n\nexport const loader = (args: LoaderFunctionArgs) =\u003e\n  authkitLoader(\n    args,\n    async ({ auth }) =\u003e {\n      return { foo: 'bar' };\n    },\n    { debug: true },\n  );\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fauthkit-remix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkos%2Fauthkit-remix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fauthkit-remix/lists"}