Gadget framework
Glossary
FAQ

Helpers 

user model 

Gadget by default sets the following fields within your user model:

  • resetPasswordTokenExpiration
  • resetPasswordToken
  • emailVerificationTokenExpiration
  • emailVerificationToken
  • password
  • googleProfileId
  • googleImageUrl
  • emailVerified
  • email
  • lastName
  • firstName
  • lastSignedIn
  • roles

Google OAuth Sign Up trigger 

This trigger executes when a new user signs up using Google OAuth. The entire profile payload from Google is included in the trigger.

Google OAuth Sign In trigger 

This trigger executes when an existing user signs in using Google OAuth. The entire profile payload from Google is included in the trigger.

Email Password Sign Up trigger 

This trigger executes when a new user signs up using Email-Password authentication. This trigger exposes the signUp action to your API.

Email Password Sign In trigger 

This trigger executes when an existing user signs in using Email-Password authentication. This trigger exposes the signIn action to your API.

Verify Email trigger 

This trigger executes the verifyEmail action. It finds a user record by emailVerificationToken and checks emailVerificationTokenExpiration to see if the token is still valid. If it is the trigger sets emailVerified to be true.

Send Verify Email trigger 

This trigger executes the sendVerifyEmail action. When the sendVerifyEmail action is called from your API, this trigger finds a user record by email and checks that emailVerified is false. It generates a random code and provides it to the action in params.user.emailVerificationCode. The user record then has emailVerificationToken set to the SHA256 hash of this code.

Reset Password trigger 

This trigger executes the resetPassword action. It finds a user record by resetPasswordToken and checks resetPasswordTokenExpiration to see if the token is still valid. If it is the trigger sets the new password.

Send Reset Password trigger 

This trigger executes the sendResetPassword action. When the sendResetPassword action is called from your API, this trigger finds a user record by email. It then generates a random code and provides it to the action in params.user.resetPasswordCode. The user record then has resetPasswordToken set to the SHA256 hash of this code.

Change Password trigger 

This trigger executes the changePassword action. It checks that the currentPassword matches the user's current password and then sets the new password.

signUp action 

A user model's signUp action is a create action by default.

Its run function includes setting the lastSignedIn field of the user record to the current date and time. This indicates when the user last signed in or, in this context, when the user created their account.

In addition, it associates the current user record with the active session.

api/models/user/actions/signUp.js
JavaScript
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers the form in web/routes/sign-up.tsx
4

5export const run: ActionRun = async ({ params, record, logger, api, session }) => {
6  // Applies new 'email' and 'password' to the user record and saves to database
7  applyParams(params, record);
8  record.lastSignedIn = new Date();
9  await save(record);
10  if (record.emailVerified) {
11    // Assigns the signed-in user to the active session
12    session?.set("user", { _link: record.id });
13  }
14  return {
15    result: "ok",
16  };
17};
18

19export const onSuccess: ActionOnSuccess = async ({
20  params,
21  record,
22  logger,
23  api,
24  session,
25}) => {
26  if (!record.emailVerified) {
27    // Sends verification email by calling api/models/users/actions/sendVerifyEmail.ts
28    await api.user.sendVerifyEmail({ email: record.email });
29  }
30};
31

32export const options: ActionOptions = {
33  actionType: "create",
34  returnType: true,
35  triggers: {
36    googleOAuthSignUp: true,
37    emailSignUp: true,
38  },
39};
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers the form in web/routes/sign-up.tsx
4

5export const run: ActionRun = async ({ params, record, logger, api, session }) => {
6  // Applies new 'email' and 'password' to the user record and saves to database
7  applyParams(params, record);
8  record.lastSignedIn = new Date();
9  await save(record);
10  if (record.emailVerified) {
11    // Assigns the signed-in user to the active session
12    session?.set("user", { _link: record.id });
13  }
14  return {
15    result: "ok",
16  };
17};
18

19export const onSuccess: ActionOnSuccess = async ({
20  params,
21  record,
22  logger,
23  api,
24  session,
25}) => {
26  if (!record.emailVerified) {
27    // Sends verification email by calling api/models/users/actions/sendVerifyEmail.ts
28    await api.user.sendVerifyEmail({ email: record.email });
29  }
30};
31

32export const options: ActionOptions = {
33  actionType: "create",
34  returnType: true,
35  triggers: {
36    googleOAuthSignUp: true,
37    emailSignUp: true,
38  },
39};

signIn action 

A user model's signIn action is an update action by default.

It updates the lastSignedIn field of the user record to the current date and time and associates the current user record with the active session.

api/models/user/actions/signIn.js
JavaScript
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/sign-in.tsx
4

5export const run: ActionRun = async ({ params, record, logger, api, session }) => {
6  applyParams(params, record);
7  record.lastSignedIn = new Date();
8  await save(record);
9  // Assigns the signed-in user to the active session
10  session?.set("user", { _link: record.id });
11};
12

13export const onSuccess: ActionOnSuccess = async ({
14  params,
15  record,
16  logger,
17  api,
18  session,
19}) => {
20  // Your logic goes here
21};
22

23export const options: ActionOptions = {
24  actionType: "update",
25  triggers: {
26    googleOAuthSignIn: true,
27    emailSignIn: true,
28  },
29};
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/sign-in.tsx
4

5export const run: ActionRun = async ({ params, record, logger, api, session }) => {
6  applyParams(params, record);
7  record.lastSignedIn = new Date();
8  await save(record);
9  // Assigns the signed-in user to the active session
10  session?.set("user", { _link: record.id });
11};
12

13export const onSuccess: ActionOnSuccess = async ({
14  params,
15  record,
16  logger,
17  api,
18  session,
19}) => {
20  // Your logic goes here
21};
22

23export const options: ActionOptions = {
24  actionType: "update",
25  triggers: {
26    googleOAuthSignIn: true,
27    emailSignIn: true,
28  },
29};

signOut action 

A user model's signOut action is an update action by default.

It unsets the associated user on the active session, causing the session to be unauthenticated.

api/models/user/actions/signOut.js
JavaScript
1import { ActionOptions } from "gadget-server";
2

3export const run: ActionRun = async ({ params, record, logger, api, session }) => {
4  // Removes the user from the active session
5  session?.set("user", null);
6};
7

8export const onSuccess: ActionOnSuccess = async ({
9  params,
10  record,
11  logger,
12  api,
13  session,
14}) => {
15  // Your logic goes here
16};
17

18export const options: ActionOptions = {
19  actionType: "update",
20  triggers: {
21    signOut: true,
22  },
23};
1import { ActionOptions } from "gadget-server";
2

3export const run: ActionRun = async ({ params, record, logger, api, session }) => {
4  // Removes the user from the active session
5  session?.set("user", null);
6};
7

8export const onSuccess: ActionOnSuccess = async ({
9  params,
10  record,
11  logger,
12  api,
13  session,
14}) => {
15  // Your logic goes here
16};
17

18export const options: ActionOptions = {
19  actionType: "update",
20  triggers: {
21    signOut: true,
22  },
23};

verifyEmail and sendVerifyEmail actions 

A user model's verifyEmail action is a default action file upon app creation, that is designated to handle email verification scenarios for users, as determined by the Gadget developer.

api/models/user/actions/verifyEmail.js
JavaScript
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers the sign up flow, this action is called from the email generated in /actions/sendVerifyEmail.ts
4

5export const run: ActionRun = async ({ params, record, logger, api }) => {
6  // Applies new 'emailVerified' status to the user record and saves to database
7  applyParams(params, record);
8  await save(record);
9  return {
10    result: "ok",
11  };
12};
13

14export const onSuccess: ActionOnSuccess = async ({
15  params,
16  record,
17  logger,
18  api,
19}) => {
20  // Your logic goes here
21};
22

23export const options: ActionOptions = {
24  actionType: "custom",
25  returnType: true,
26  triggers: {
27    verifiedEmail: true,
28  },
29};
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers the sign up flow, this action is called from the email generated in /actions/sendVerifyEmail.ts
4

5export const run: ActionRun = async ({ params, record, logger, api }) => {
6  // Applies new 'emailVerified' status to the user record and saves to database
7  applyParams(params, record);
8  await save(record);
9  return {
10    result: "ok",
11  };
12};
13

14export const onSuccess: ActionOnSuccess = async ({
15  params,
16  record,
17  logger,
18  api,
19}) => {
20  // Your logic goes here
21};
22

23export const options: ActionOptions = {
24  actionType: "custom",
25  returnType: true,
26  triggers: {
27    verifiedEmail: true,
28  },
29};

The sendVerifyEmail action, is a custom action that updates the user record with the provided parameters and then, if successful, it sends an email to the user containing a reset password link.

api/models/user/actions/sendVerifyEmail.js
JavaScript
1import {
2  applyParams,
3  save,
4  ActionOptions,
5  DefaultEmailTemplates,
6  Config,
7} from "gadget-server";
8

9// Powers the sign up flow, this action is called from api/models/user/actions/signUp.ts
10

11export const run: ActionRun = async ({ params, record, logger, api, emails }) => {
12  // Applies new hashed code 'emailVerificationToken' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  emails,
26}) => {
27  if (
28    !record.emailVerified &&
29    record.emailVerificationToken &&
30    params.user?.emailVerificationCode
31  ) {
32    // Generates link to reset password
33    const url = new URL("/verify-email", Config.appUrl);
34    url.searchParams.append("code", params.user?.emailVerificationCode);
35    // Sends link to user
36    await emails.sendMail({
37      to: record.email,
38      subject: `Verify your email with ${Config.appName}`,
39      html: DefaultEmailTemplates.renderVerifyEmailTemplate({ url: url.toString() }),
40    });
41  }
42};
43

44export const options: ActionOptions = {
45  actionType: "custom",
46  returnType: true,
47  triggers: {
48    sendVerificationEmail: true,
49  },
50};
1import {
2  applyParams,
3  save,
4  ActionOptions,
5  DefaultEmailTemplates,
6  Config,
7} from "gadget-server";
8

9// Powers the sign up flow, this action is called from api/models/user/actions/signUp.ts
10

11export const run: ActionRun = async ({ params, record, logger, api, emails }) => {
12  // Applies new hashed code 'emailVerificationToken' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  emails,
26}) => {
27  if (
28    !record.emailVerified &&
29    record.emailVerificationToken &&
30    params.user?.emailVerificationCode
31  ) {
32    // Generates link to reset password
33    const url = new URL("/verify-email", Config.appUrl);
34    url.searchParams.append("code", params.user?.emailVerificationCode);
35    // Sends link to user
36    await emails.sendMail({
37      to: record.email,
38      subject: `Verify your email with ${Config.appName}`,
39      html: DefaultEmailTemplates.renderVerifyEmailTemplate({ url: url.toString() }),
40    });
41  }
42};
43

44export const options: ActionOptions = {
45  actionType: "custom",
46  returnType: true,
47  triggers: {
48    sendVerificationEmail: true,
49  },
50};

resetPassword and sendResetPassword actions 

A user model's resetPassword action is a default action file upon app creation, that is designated to handle password reset scenarios for users, as determined by the Gadget developer.

api/models/user/actions/resetPassword.js
JavaScript
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/reset-password.tsx
4

5export const run: ActionRun = async ({
6  params,
7  record,
8  logger,
9  api,
10  connections,
11}) => {
12  // Applies new 'password' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  connections,
26}) => {
27  // Your logic goes here
28};
29

30export const options: ActionOptions = {
31  actionType: "custom",
32  returnType: true,
33  triggers: {
34    resetPassword: true,
35  },
36};
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/reset-password.tsx
4

5export const run: ActionRun = async ({
6  params,
7  record,
8  logger,
9  api,
10  connections,
11}) => {
12  // Applies new 'password' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  connections,
26}) => {
27  // Your logic goes here
28};
29

30export const options: ActionOptions = {
31  actionType: "custom",
32  returnType: true,
33  triggers: {
34    resetPassword: true,
35  },
36};

The sendResetPassword action, is a custom action that updates the user record with the provided parameters and then, if successful, the action will send a verification email containing a unique link for the user to verify their email.

api/models/user/actions/sendResetPassword.js
JavaScript
1import {
2  applyParams,
3  save,
4  ActionOptions,
5  DefaultEmailTemplates,
6  Config,
7} from "gadget-server";
8

9// Powers form in web/routes/forgot-password.tsx
10

11export const run: ActionRun = async ({ params, record, logger, api, emails }) => {
12  // Applies new hashed code 'resetPasswordToken' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  emails,
26}) => {
27  if (record.resetPasswordToken && params.user?.resetPasswordCode) {
28    // Generates link to reset password
29    const url = new URL("/reset-password", Config.appUrl);
30    url.searchParams.append("code", params.user?.resetPasswordCode);
31    // Sends link to user
32    await emails.sendMail({
33      to: record.email,
34      subject: `Reset password request from ${Config.appName}`,
35      html: DefaultEmailTemplates.renderResetPasswordTemplate({
36        url: url.toString(),
37      }),
38    });
39  }
40};
41

42export const options: ActionOptions = {
43  actionType: "custom",
44  returnType: true,
45  triggers: {
46    sendResetPassword: true,
47  },
48};
1import {
2  applyParams,
3  save,
4  ActionOptions,
5  DefaultEmailTemplates,
6  Config,
7} from "gadget-server";
8

9// Powers form in web/routes/forgot-password.tsx
10

11export const run: ActionRun = async ({ params, record, logger, api, emails }) => {
12  // Applies new hashed code 'resetPasswordToken' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15  return {
16    result: "ok",
17  };
18};
19

20export const onSuccess: ActionOnSuccess = async ({
21  params,
22  record,
23  logger,
24  api,
25  emails,
26}) => {
27  if (record.resetPasswordToken && params.user?.resetPasswordCode) {
28    // Generates link to reset password
29    const url = new URL("/reset-password", Config.appUrl);
30    url.searchParams.append("code", params.user?.resetPasswordCode);
31    // Sends link to user
32    await emails.sendMail({
33      to: record.email,
34      subject: `Reset password request from ${Config.appName}`,
35      html: DefaultEmailTemplates.renderResetPasswordTemplate({
36        url: url.toString(),
37      }),
38    });
39  }
40};
41

42export const options: ActionOptions = {
43  actionType: "custom",
44  returnType: true,
45  triggers: {
46    sendResetPassword: true,
47  },
48};

changePassword action 

A user model's changePassword action is a default action file upon app creation, that is designated to handle scenarios for users where they have to change/update their password, as determined by the Gadget developer.

api/models/user/actions/changePassword.js
JavaScript
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/change-password.tsx
4

5export const run: ActionRun = async ({
6  params,
7  record,
8  logger,
9  api,
10  connections,
11}) => {
12  // Applies new 'password' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15};
16

17export const onSuccess: ActionOnSuccess = async ({
18  params,
19  record,
20  logger,
21  api,
22  connections,
23}) => {
24  // Your logic goes here
25};
26

27export const options: ActionOptions = {
28  actionType: "update",
29  triggers: {
30    changePassword: true,
31  },
32};
1import { applyParams, save, ActionOptions } from "gadget-server";
2

3// Powers form in web/routes/change-password.tsx
4

5export const run: ActionRun = async ({
6  params,
7  record,
8  logger,
9  api,
10  connections,
11}) => {
12  // Applies new 'password' to the user record and saves to database
13  applyParams(params, record);
14  await save(record);
15};
16

17export const onSuccess: ActionOnSuccess = async ({
18  params,
19  record,
20  logger,
21  api,
22  connections,
23}) => {
24  // Your logic goes here
25};
26

27export const options: ActionOptions = {
28  actionType: "update",
29  triggers: {
30    changePassword: true,
31  },
32};

session model 

All Gadget apps have a session model that is used to power session management. The current session is always available in Gadget actions and route handlers:

api/actions/someAction.js
JavaScript
export const run: ActionRun = async ({ params, record, logger, api, session }) => {
  logger.info({ session }, "the session associated with the current request");
};
export const run: ActionRun = async ({ params, record, logger, api, session }) => {
  logger.info({ session }, "the session associated with the current request");
};

csrfToken 

All session records have a special csrfToken property that can be used to prevent cross-site request forgery (CSRF) attacks.

Gadget automatically checks CSRF tokens for all form submission requests. To submit a form as an authenticated user you must include the CSRF token in the form data.

api/routes/GET-a-form.js
JavaScript
1import { RouteHandler } from "gadget-server";
2

3const route: RouteHandler = async ({ request, reply, api, logger, connections }) => {
4  // send an HTML response with a form that has a CSRF token
5  await reply.send(`
6  <html>
7    <body>
8      <form method="POST" action="/submit-form">
9        <input type="hidden" name="csrfToken" value="${session.csrfToken}" />
10        <button type="submit">Submit</button>
11      </form>
12    </body>
13  </html>
14  `);
15};
16

17export default route;
1import { RouteHandler } from "gadget-server";
2

3const route: RouteHandler = async ({ request, reply, api, logger, connections }) => {
4  // send an HTML response with a form that has a CSRF token
5  await reply.send(`
6  <html>
7    <body>
8      <form method="POST" action="/submit-form">
9        <input type="hidden" name="csrfToken" value="${session.csrfToken}" />
10        <button type="submit">Submit</button>
11      </form>
12    </body>
13  </html>
14  `);
15};
16

17export default route;

Custom auth state parameters 

You can add custom auth action parameters to the built in auth flow by:

  • Adding a custom parameter to the signup and/or signin actions:
api/models/user/actions/signUp or signIn
JavaScript
export const params = {
  example: { type: "string" },
};
export const params = {
  example: { type: "string" },
};
  • Adding the query parameter to the auth kickoff:
JavaScript
1// In frontend code
2<a className="google-oauth-button" href={`/auth/google/start${search}?example=true`}>
3  <img
4    src="https://assets.gadget.dev/assets/default-app-assets/google.svg"
5    width={22}
6    height={22}
7  />{" "}
8  Continue with Google
9</a>;
1// In frontend code
2<a className="google-oauth-button" href={`/auth/google/start${search}?example=true`}>
3  <img
4    src="https://assets.gadget.dev/assets/default-app-assets/google.svg"
5    width={22}
6    height={22}
7  />{" "}
8  Continue with Google
9</a>;
  • Pulling the value from the params action context:
api/models/user/actions/signUp or signIn
JavaScript
1export const run: ActionRun = async ({ params, record, logger, api, session }) => {
2  applyParams(params, record);
3

4  const { example } = params;
5  // ...
6};
1export const run: ActionRun = async ({ params, record, logger, api, session }) => {
2  applyParams(params, record);
3

4  const { example } = params;
5  // ...
6};

Hooks and components 

When working with Gadget authentication, there are several hooks and components from our @gadgetinc/react package that can help you manage the authentication state of your application.

The hooks use the Gadget client's suspense: true option, making it easier to manage the async nature of the hooks without having to deal with loading state.

HooksDescription
useSession()Retrieves the current user session within the app.
useUser()If a user is present in the session, it returns the current user; otherwise, it returns null for unauthenticated sessions.
useAuth()Returns an object representing the current authentication state of the session.
useSignOut()Returns a callback that you can call to sign out your current Gadget User from the current Session. This calls the configured signOutActionApiIdentifier action, which is the User signOut action by default.
ComponentsDescription
<SignedIn />Conditionally renders its children if the current session has a user associated with it, similar to the isSignedIn property of the useAuth() hook.
<SignedOut />Conditionally renders its children if the current session does not have a user associated with it.
<SignedInOrRedirect />Conditionally renders its children based on the user's sign-in status. If a user is currently signed in, it displays its children; otherwise, it redirects the browser using window.location.assign. This functionality is valuable for securing frontend routes.
<SignedOutOrRedirect />Conditionally renders its children when there is no user associated with the current session. However, if the user is signed in, it redirects the browser using window.location.assign. Its purpose is to facilitate redirection of frontend routes based on the user's sign-in status.

Was this page helpful?