|
1 | | -# Remix Auth - Strategy Template |
| 1 | +# remix-auth-guilded |
2 | 2 |
|
3 | | -> A template for creating a new Remix Auth strategy. |
| 3 | +remix-auth strategy for Authlink, an OAuth2 provider for Guilded. If you prefer Next.js, see [next-auth-guilded](https://github.com/GuildedAPI/next-auth-guilded). |
4 | 4 |
|
5 | | -If you want to create a new strategy for Remix Auth, you could use this as a template for your repository. |
| 5 | +## Supported runtimes |
6 | 6 |
|
7 | | -The repo installs the latest version of Remix Auth and do the setup for you to have tests, linting and typechecking. |
| 7 | +| Runtime | Has Support | |
| 8 | +| ---------- | ----------- | |
| 9 | +| Node.js | ✅ | |
| 10 | +| Cloudflare | ✅ | |
8 | 11 |
|
9 | | -## How to use it |
| 12 | +## How to use |
10 | 13 |
|
11 | | -1. In the `package.json` change `name` to your strategy name, also add a description and ideally an author, repository and homepage keys. |
12 | | -2. In `src/index.ts` change the `MyStrategy` for the strategy name you want to use. |
13 | | -3. Implement the strategy flow inside the `authenticate` method. Use `this.success` and `this.failure` to correctly send finish the flow. |
14 | | -4. In `tests/index.test.ts` change the tests to use your strategy and test it. Inside the tests you have access to `jest-fetch-mock` to mock any fetch you may need to do. |
15 | | -5. Once you are ready, set the secrets on Github |
16 | | - - `NPM_TOKEN`: The token for the npm registry |
17 | | - - `GIT_USER_NAME`: The git username you want the bump workflow to use in the commit. |
18 | | - - `GIT_USER_EMAIL`: The email you want the bump workflow to use in the commit. |
| 14 | +### Create an Authlink application |
19 | 15 |
|
20 | | -## Scripts |
| 16 | +Visit https://authlink.app/dev/apps, press "new", and connect your Guilded bot to finalize the application. Add a redirect URI and note down your client ID and secret (you will need to press "reset" to generate a secret). You may also configure a vanity code with preconfigured options, though beware that these can be overridden. |
21 | 17 |
|
22 | | -- `build`: Build the project for production using the TypeScript compiler (strips the types). |
23 | | -- `typecheck`: Check the project for type errors, this also happens in build but it's useful to do in development. |
24 | | -- `lint`: Runs ESLint against the source codebase to ensure it pass the linting rules. |
25 | | -- `test`: Runs all the test using Jest. |
| 18 | +### Create session storage |
26 | 19 |
|
27 | | -## Documentations |
| 20 | +```ts |
| 21 | +// app/session.server.ts |
| 22 | +import { createCookieSessionStorage } from "@remix-run/node"; |
28 | 23 |
|
29 | | -To facilitate creating a documentation for your strategy, you can use the following Markdown |
| 24 | +export const sessionStorage = createCookieSessionStorage({ |
| 25 | + cookie: { |
| 26 | + name: "_session", |
| 27 | + sameSite: "lax", |
| 28 | + path: "/", |
| 29 | + httpOnly: true, |
| 30 | + secrets: ["s3cr3t"], |
| 31 | + secure: process.env.NODE_ENV === "production", |
| 32 | + }, |
| 33 | +}); |
30 | 34 |
|
31 | | -```markdown |
32 | | -# Strategy Name |
| 35 | +export const { getSession, commitSession, destroySession } = sessionStorage; |
| 36 | +``` |
33 | 37 |
|
34 | | -<!-- Description --> |
| 38 | +### Create the strategy instance |
| 39 | + |
| 40 | +```ts |
| 41 | +// app/auth.server.ts |
| 42 | +import { Authenticator } from "remix-auth"; |
| 43 | +import { GuildedStrategy, type GuildedUser } from "remix-auth-guilded"; |
| 44 | +import { sessionStorage } from "~/session.server"; |
| 45 | + |
| 46 | +export interface GuildedAuth { |
| 47 | + id: string; |
| 48 | + name: string; |
| 49 | + avatar: string | null; |
| 50 | + banner: string | null; |
| 51 | + accessToken: string; |
| 52 | + refreshToken: string; |
| 53 | +} |
| 54 | + |
| 55 | +export const auth = new Authenticator<DiscordAuth>(sessionStorage); |
| 56 | + |
| 57 | +const guildedStrategy = new GuildedStrategy( |
| 58 | + { |
| 59 | + clientId: "YOUR_CLIENT_ID", |
| 60 | + clientSecret: "YOUR_CLIENT_SECRET", |
| 61 | + redirectUri: "https://example.com/auth/guilded/callback", |
| 62 | + scope: ["identify"], |
| 63 | + }, |
| 64 | + // OR { clientId, clientSecret, vanity: "..." } |
| 65 | + async ({ |
| 66 | + accessToken, |
| 67 | + refreshToken, |
| 68 | + extraParams, |
| 69 | + profile, |
| 70 | + }): Promise<DiscordAuth> => { |
| 71 | + // This package does not fetch the user for you |
| 72 | + const user = await this.getUser(accessToken) |
| 73 | + |
| 74 | + // This goes into your sessionStorage and is also returned by |
| 75 | + // this method if successRedirect is not provided |
| 76 | + return { |
| 77 | + id: user.id, |
| 78 | + name: user.name, |
| 79 | + avatar: user.avatar, |
| 80 | + banner: user.banner, |
| 81 | + accessToken, |
| 82 | + refreshToken, |
| 83 | + }; |
| 84 | + }, |
| 85 | +); |
| 86 | + |
| 87 | +auth.use(guildedStrategy); |
| 88 | +``` |
35 | 89 |
|
36 | | -## Supported runtimes |
| 90 | +### Use in a loader |
37 | 91 |
|
38 | | -| Runtime | Has Support | |
39 | | -| ---------- | ----------- | |
40 | | -| Node.js | ✅ | |
41 | | -| Cloudflare | ✅ | |
| 92 | +```ts |
| 93 | +// app/routes/auth.guilded.callback.tsx |
| 94 | +import type { LoaderFunction } from "@remix-run/node"; |
| 95 | +import { auth } from "~/auth.server"; |
42 | 96 |
|
43 | | -<!-- If it doesn't support one runtime, explain here why --> |
| 97 | +export const loader: LoaderFunction = ({ request }) => { |
| 98 | + return auth.authenticate("guilded", request, { |
| 99 | + successRedirect: "/dashboard", |
| 100 | + failureRedirect: "/login", |
| 101 | + }); |
| 102 | +}; |
| 103 | +``` |
44 | 104 |
|
45 | | -## How to use |
| 105 | +## Attribution |
46 | 106 |
|
47 | | -<!-- Explain how to use the strategy, here you should tell what options it expects from the developer when instantiating the strategy --> |
48 | | -``` |
| 107 | +Design elements & examples from [remix-auth-discord](https://github.com/JonnyBnator/remix-auth-discord). |
0 commit comments