Javascript

How to Set Up OAuth with a Stripe App

Published May 24, 2022

Updated Feb 13, 2023

8 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Stripe Apps are a great way to extend Stripe dashboard functionality using third-party integrations. But when using these integrations, developers must prioritize security. The best way to do this is by using OAuth with the third-party product with which you would like to integrate.

However, there are some constraints, and we cannot use cookies to set up a cookie based authentication front-end only. In this article, we would like to show you how to do it with a NestJS back-end.

Stripe signatures

The best way to secure your API is by making sure that every request comes from a verified Stripe App instance. The @stripe/ui-extension-sdk package provides a way to generate a signature on the front-end side. This signature is valid for 5 minutes, and you can send it as a header for every request you make. For this to work, you need to have @stripe/ui-extension-sdk installed in your repository.

import fetchStripeSignature from "@stripe/ui-extension-sdk/signature";
// fetchStripeSignature returns with a Promise<string>

In order to properly validate this signature on your API, you will need some additional information to be sent in the request headers as well. That information is the Stripe user's ID, and the Stripe account's ID. We found that the best way is to implement a global context with this information.

import { createContext } from "react";
import { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
export const GlobalContext = createContext<{
  userContext: ExtensionContextValue["userContext"] | null;
  environment: ExtensionContextValue["environment"] | null;
}>({ userContext: null, environment: null });

The above context stores the ExtensionContextValue that gets passed from the Stripe dashboard to the app when it opens in the view. For example, if you are on a payment detail page, the userContext will contain information about your Stripe user, while the environment will provide you access to the object that you are viewing. In the above example, that would be the payment's ID as the objectContext.id property.

Let's set up the view with this global context.

import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
import { ContextView } from "@stripe/ui-extension-sdk/ui";
import { GlobalContext } from "./common/global-context";
const PaymentDetailView = ({
  userContext,
  environment,
}: ExtensionContextValue) => (
  <ContextView title={title || " "} description={description}>
    <GlobalContext.Provider value={{ userContext, environment }}>
      TODO: navigation and login will come here.
    </GlobalContext.Provider>
  </ContextView>
);
export default PaymentDetailView;

Now, we can set up a hook to provide a proper fetch method that always appends a Stripe signature, and the other required fields to the headers.

useFetchWithCredentials hook

In order to make our future job easier, we need to set up a hook that creates a proper wrapper around fetch. That wrapper will handle setting the headers for us. It needs to have access to our GlobalContext, so we can get the Stripe user's, and their account's, IDs.

import { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
import fetchStripeSignature from "@stripe/ui-extension-sdk/signature";
import { useCallback, useContext } from "react";
import { GlobalContext } from "../common/global-context";
export function useFetchWithCredentials() {
  const globalContext = useContext(GlobalContext);
  return useCallback(
    async (uri: string, { headers, ...options }: RequestInit = {}) => {
      const stripeSignature = await fetchStripeSignature();
      const headersObject = new Headers(headers);
      headersObject.append("stripe-signature", stripeSignature);
      headersObject.append("Content-Type", "application/json");
      headersObject.append(
        "stripe-user-id",
        globalContext.userContext?.id ?? ""
      );
      headersObject.append(
        "stripe-account-id",
        globalContext.userContext?.account.id ?? ""
      );
      return fetch(uri, {
        ...options,
        headers: headersObject,
      });
    },
    [globalContext]
  );
}

Let's set up a very basic component for demonstrating the use of the useFetchWithCredentials hook. This component will be the default route for our app's navigation wrapper. It is going to handle more later. But for now, let's just implement a basic use for our hook. The AUTH_INIT_URL constant will point at our back-end's /api/oauth/userinfo endpoint.

Please note that, for this to work, you are going to need to install react-router-dom.

import { Box, Spinner } from "@stripe/ui-extension-sdk/ui";
import { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { AUTH_INIT_URL } from "../constants/auth.urls";
import { setUser } from "../auth/state";
import { useFetchWithCredentials } from "../hooks/useFetchWithCredentials";
export const AuthInit: React.FC<{ redirectPath: string }> = ({
  redirectPath,
}) => {
  // Please note, that we are going to set the whole routing up in a later article.
  const navigate = useNavigate();
  const fetchWithCredentials = useFetchWithCredentials();
  useEffect(() => {
    fetchWithCredentials(AUTH_INIT_URL)
      .then((user) => {
        // Make sure you set the user in your chosen global state management tool.
        setUser(user);
        // For now if the response is a success response (status 200), we are going to navigate to the first authenticated route.
        navigate(redirectPath);
      })
      .catch((e) => {
        console.error(e.message);
        // If the request returns with an error (status 401), it means that the user is unauthenticated, so we send them to the login page
        navigate("/login");
      });
  }, [redirectPath]);
  // Let's display a spinner while we wait for our initial request to return.
  return (
    <Box
      css={{
        layout: "column",
        alignX: "center",
        alignY: "center",
      }}
    >
      <Spinner size="large" />
      Loading...
    </Box>
  );
};

As we can see from the above implementation, this component will be the initial component that gets rendered inside of the application. It will send out a request to determine if the user is logged in. If they are logged in, we are going to send them to a route that is the first page of our application. If they are not signed in, we are going to redirect them to our login page. This initial call, just as every other API call, must be verified and always have a Stripe signature.

Let's visualise how routing looks like right now:

import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
import { ContextView } from "@stripe/ui-extension-sdk/ui";
import { GlobalContext } from "./common/global-context";
import { Route, Routes } from 'react-router-dom';
import { PaymentInfo } from './components/PaymentInfo;
const PaymentDetailView = ({
  userContext,
  environment,
}: ExtensionContextValue) => (
  <ContextView title={title || " "} description={description}>
    <GlobalContext.Provider value={{ userContext, environment }}>
      <Router basename="/" initialEntries={['/init']}>
        <Routes>
          <Route
            path="/init"
            element={<AuthInit redirectPath={'/payment-details'} />}
          />
          <Route path="/login" element={<Login />} />
          <Route path="/payment-details" element={<PaymentInfo />}>
        </Routes>
      </Router>
    </GlobalContext.Provider>
  </ContextView>
);
export default PaymentDetailView;

Stripe secrets and the Stripe API

In order to be able to use the Stripe NodeJS Api, you will need two secrets from Stripe. One is your Stripe account's API key, and the other one is your Stripe-app's secret. You need to set up your .env file as the following.

STRIPE_API_KEY='your api key goes here'
STRIPE_APP_SECRET='your app secret goes here'

Stripe API key

You can find your Stripe API key at https://dashboard.stripe.com/apikeys, under the Standard keys section. The key you are looking for is called Secret key, and you need to reveal it by clicking the button that hides it.

Stripe App Secret

For this key, you are going to need to upload your stripe-app using the stripe apps upload command. Make sure that you set a development app ID in your app manifest (stripe-app.json). After you uploaded your app, visit https://dashboard.stripe.com/apps. Under My Apps, you should see your uploaded application. Open it and search for the Signing secret. Reveal it and copy it into your .env file.

Stripe NodeJS API

Please make sure you have installed the stripe nmp package for your server code. In this example series, we use NestJS as our framework for our API. We need the above two secret keys to be able to start up our Stripe API.

// verify-signature.ts
import { BadRequestException, Logger } from "@nestjs/common";
import { Stripe } from "stripe";
const STRIPE_API = new Stripe(process.env.STRIPE_API_KEY, {
  apiVersion: "2020-08-27",
});
const APP_SECRET = process.env.STRIPE_APP_SECRET;
export function verifySignature(
  userId: string,
  accountId: string,
  signature: string,
  logger: Logger
): void {
  // Signature verification will come here
}

NestJS VerifySignatureInterceptor implementation

In NestJS, we can use interceptors to abstract away repetitive logic that needs to be done on multiple requests. In our case, we need to verify almost every API for a valid Stripe signature. We have access to the proper secret keys, and we have a Stripe NodeJS API set up. Let's create our VerifySignatureInterceptor.

import {
  BadRequestException,
  CallHandler,
  ExecutionContext,
  Injectable,
  Logger,
  NestInterceptor,
} from "@nestjs/common";
import { Request } from "express";
import { Observable } from "rxjs";
import { Stripe } from "stripe";
const STRIPE_API = new Stripe(process.env.STRIPE_API_KEY, {
  apiVersion: "2020-08-27",
});
const APP_SECRET = process.env.STRIPE_APP_SECRET;
@Injectable()
export class VerifySignatureInterceptor implements NestInterceptor {
  // We set up a logger instance, so we can properly log errors
  private readonly logger = new Logger(VerifySignatureInterceptor.name);
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const req: Request = context.switchToHttp().getRequest();
    const signature = req.headers["stripe-signature"] as string;
    const userId = req.headers["stripe-user-id"] as string;
    const accountId = req.headers["stripe-account-id"] as string;
    verifySignature(userId, accountId, signature, this.logger);
    return next.handle();
  }
}

Every interceptor must implement the intercept() method. We extract the Request object from the execution context, and we get the headers that we previously set in our useFetchWithCredentials hook. We call our verifySignature function which will throw errors if the signature is invalid. We also pass the Logger instance, so we can determine when an error comes from this interceptor in our logs.

Please be aware that there are several reasons signature verification can go wrong, like if we provide the wrong Stripe account keys or app secrets. In order for you to be able to easily debug these issues, proper logging is a must. That is why we set up a Logger instance in our interceptor.

// ...
export function verifySignature(
  userId: string,
  accountId: string,
  signature: string,
  logger: Logger
): void {
  if (!(user_id && account_id && signature)) {
    throw new BadRequestException("Missing user identifiers");
  }
  try {
    stripe.webhooks.signature.verifyHeader(
      JSON.stringify({ user_id, account_id }),
      signature,
      APP_SECRET
    );
  } catch (e: any) {
    logger.error(`Could not verify signature due to: ${e.message}`);
    throw new BadRequestException("Could not verify signature");
  }
}

If the user_id, account_id, or the signature are missing, that could mean that the request came from outside a stripe application, or the useFetchWithCredentials hook was not used. We throw a BadRequestException that will result in the request sending back a status: 400 HTTP response.

If the signature verification fails, that could mean that a not valid signature was used in the request, or that the API environment variables might have the wrong keys.

Set up the userinfo endpoint

Let's quickly set up our /api/oauth/userinfo endpoint. For that, we are going to create the OauthModule and the OauthController.

// oauth.module.ts
import { Module } from "@nestjs/common";
import { OauthController } from "./oauth.controller";
@Module({
  controllers: [OauthController],
})
export class OauthModule {}

In our controller, we decorate our getUserInfo() method, with the @Get() decorator, so we set up the route. We also decorate the method with the @UseInterceptors() decorator, where we pass our VerifySignatureInterceptor.

// oauth.controller.ts
import {
  Controller,
  Get,
  Headers,
  Logger,
  UnauthorizedException,
  UseInterceptors,
} from "@nestjs/common";
import { VerifySignatureInterceptor } from "./interceptors/verify-signature.interceptor";
import { UserInfo } from "../interfaces/user";
@Controller("oauth")
export class OauthController {
  // We set up our Logger instance here as well
  private readonly logger = new Logger(OauthController.name);
  @Get("userinfo")
  @UseInterceptors(VerifySignatureInterceptor)
  async getUserInfo(
    @Headers("stripe-account-id") accountId: string,
    @Headers("stripe-user-id") userId: string
  ): Promise<UserInfo> {
    // For now, we always throw an unauthorised exception, so our front-end will load the login page
    throw new UnauthorizedException();
  }
}

This setup will enable us to call the /api/oauth/userinfo endpoint which will, in-turn, check if we have a valid signature present in the headers. If the request is invalid, it will throw a 400 Bad Request exception. If the signature is valid, for now, we will throw a 401 Unauthorized exception just to make our front-end navigate to the login page.

Just to keep this example simple, our login page will only have a button in the center that will start our login flow with our API.

import fetchStripeSignature from '@stripe/ui-extension-sdk/signature';
import { LOGIN_URI } from '../../constants/url.constants';
import { Box, Button } from '@stripe/ui-extension-sdk/ui';
import { GlobalContext } from '../../common/global-context';
export const Login: React.FC = () => {
  const globalContext = useContext(GlobalContext);
  const [stateKey, setStateKey] = useState<string | null>(null);
  // setting the stateKey will be implemented here
  const queryParams = new URLSearchParams({
    state: stateKey as string,
  })
  // LOGIN_URI points to our API at the '/api/oauth/login' endpoint
  const loginUrl = `${LOGIN_URI}?${queryParams}`
  return (
      <Box css={{
            height: 'fill',
            width: 'fill,
            layout: 'row',
            alignX: 'center',
            alignY: 'center'
      }}>
        <Button
            type="primary"
            css={{
                width: 'fill',
                alignX: 'center',
            }}
            disabled={!stateKey}
            href={loginUrl}
        >
          Sign in
        </Button>
      </Box>
  )
}

We need to create a state key, that can be validated before we fetch the token. This state key will first be sent to our third-party oauth client, and it will be returned to us when the authentication is finished. This key is passed securely and over https. Therefore, it can be a stringified object. While the key is not set, we disable the button.

import fetchStripeSignature from "@stripe/ui-extension-sdk/signature";
import { LOGIN_URI } from "../../constants/url.constants";
import { Box, Button } from "@stripe/ui-extension-sdk/ui";
import { GlobalContext } from "../../common/global-context";
export const Login: React.FC = () => {
  const globalContext = useContext(GlobalContext);
  const [stateKey, setStateKey] = useState<string | null>(null);
  useEffect(() => {
    // we create an async function which will get all the necessary data and then call JSON.stringify() on it
    const getStateKey = async () => {
      const signature = await fetchStripeSignature();
      const userId = globalContext.userContext?.id;
      const accountId = globalContext.userContext?.account.id;
      return JSON.stringify({ userId, accountId, signature });
    };
    getStateKey().then(setStateKey);
  }, [globalContext.userContext]);
  const queryParams = new URLSearchParams({
    state: stateKey as string,
  });
  // LOGIN_URI points to our API at the '/api/oauth/login' endpoint
  const loginUrl = `${LOGIN_URI}?${queryParams}`;
  return {
    /* ... */
  };
};

Pressing the Sign in button will call our API that will redirect us to our third-party login screen. When the login happens, it will redirect us to our API, where we can fetch a valid token and redirect again to the Stripe dashboard. Let's extend our environment variables.

STRIPE_API_KEY='your api key goes here'
STRIPE_APP_SECRET='your app secret goes here'
STRIPE_REDIRECT_URL='https://dashboard.stripe.com/test/apps-oauth/your.app.id'
## The above url is set to the development preview redirect url. In production, this url will look like the following:
## STRIPE_REDIRECT_URL='https://dashboard.stripe.com/apps-oauth/your.app.id'
## Don't forget that your app-id in development and in production should be different
THIRD_PARTY_CLIENT_ID='your client id goes here'
THIRD_PARTY_CLIENT_SECRET='your client secret goes here'
THIRD_PARTY_URL_BASE='https://third-party.com'
API_HOST_URL='http://localhost:3333'
## In production, the above url should point to your deployed back-end

Now that we have every environment variable set up, let's implement our api/oauth/login and api/oauth/authorise endpoints in our OauthController.

// ...
const THIRD_PARTY_OAUTH_URL = `${process.env.THIRD_PARTY_URL_BASE}/oauth`;
const API_AUTH_CALLBACK_URL = `${process.env.API_HOST_URL}/api/oauth/authorise`;
@Controller("oauth")
export class OauthController {
  // ...
  @Get("login")
  @Redirect(THIRD_PARTY_OAUTH_URL, 303)
  // the HasValuePipe checks if the state is not an empty string or undefined.
  login(@Query("state", HasValuePipe) state: string): { url: string } {
    const queryParams = new URLSearchParams({
      response_type: "code",
      client_id: process.env.THIRD_PARTY_CLIENT_ID,
      redirect_uri: API_AUTH_CALLBACK_URL,
      state,
    });
    // with the query parameters set, we redirect to our third-party oauth page
    return {
      url: `${THIRD_PARTY_OAUTH_URL}?${queryParams.toString()}`,
    };
  }
}

The login endpoint, if everything is correct, redirects us to the login page where the user should be able to log in. Make sure that if you oauth client needs to have configured redirect urls, you configure them. For example, for development, the http://localhost:3333/api/oauth/authorise endpoint should be in the allowed redirect url list.

@Controller("oauth")
export class OauthController {
  // ...
  @Get("authorize")
  @Redirect(process.env.STRIPE_REDIRECT_URL, 303)
  async loggedIn(
    @Query("state", HasValuePipe) state: string,
    @Query("code", HasValuePipe) code: string
  ) {
    // If either the state or the code is missing, we return with a 400 Bad Request response
    if (!state || !code) {
      throw new BadRequestException();
    }
    let userId: string;
    let accountId: string;
    let signature: string;
    try {
      const _ = ({ userId, accountId, signature } = JSON.parse(state));
    } catch (error: any) {
      // If the state is not a valid JSON we can be sure that we won't be able to
      this.logger.error(`Invalid state returned to the authorise endpoint`);
      throw new BadRequestException();
    }
    // We verify the signature to make sure it comes from our Stripe app.
    verifySignature(userId, accountId, signature, this.logger);
    // see implementation below
    await this.fetchToken(accountId, userId, code).catch(
      (error: AxiosError) => {
        if (error.response) {
          throw new UnauthorizedException();
        }
        throw new InternalServerErrorException(
          "Cannot contact authentication server"
        );
      }
    );
  }
}

We validate everything to be sure that this endpoint was called from our third-party OAuth page. With the information available to us, we can fetch the access token and store it in the Stripe Secret Storage. In this example, we use axios in our bakc-end to send requests to our third-party API.

// ...
const THIRD_PARTY_TOKEN_URI = `${process.env.THIRD_PARTY_URL_BASE}/token`;
@Controller("oauth")
export class OauthController {
  // ...
  constructor(private secretService: SecretService) {}
  // ...
  private async fetchToken(
    accountId: string,
    userId: string,
    code: string
  ): Promise<void> {
    const data = {
      grant_type: "authorization_code",
      client_id: process.env.THIRD_PARTY_CLIENT_ID,
      client_secret: process.env.THIRD_PARTY_CLIENT_SECRET,
      code,
    };
    const response = await axios.post(THIRD_PARTY_TOKEN_URI, data, {
      responseType: "json",
    });
    // Please note that the third-party API you integrate with might have a different response structure.
    const { access_token } = response.data;
    // We set the token in the secret store. See the implementation below. The Secret Store only accepts strings as values.
    // The accountId is needed so we can scope the request to the requestor user's Stripe account.
    // The userId is needed so we can use the requestor user's secrets
    // We set the secret name to 'access_token', and we pass the token as its value.
    await this.secretService.addSecret(
      accountId,
      userId,
      "access_token",
      access_token
    );
  }
}

We exchange our code returned from our OAuth client to a valid access token, and then store it in the Stripe Secret Store. That logic got extracted into a SecretService class, because the logic implemented in it can be reused later for other API calls. Please make sure you set up a NestJS module that exports this service.

Stripe Secret Store

Stripe's Secret Store API enables your app to securely store and retrieve strings that can be authentication credentials, tokens, etc. This API enables users to stay logged in to third party services even when they log out of their Stripe dashboard. Let's set up a service that handles access to the Secret Store on our back-end.

import { Stripe } from "stripe";
interface Secret {
  id: string;
  name: string;
  payload: string;
}

// With the below setup, we can communicate with the Stripe Secret Store.
const SecretResource = Stripe.StripeResource.extend({
  find: Stripe.StripeResource.method({
    method: "GET",
    path: "apps/secrets/find",
  }) as (...args: any[]) => Promise<Secret>,
  set: Stripe.StripeResource.method({
    method: "POST",
    path: "apps/secrets",
  }) as (...args: any[]) => Promise<Secret>,
  delete: Stripe.StripeResource.method({
    method: "POST",
    path: "apps/secrets/delete",
  }) as (...args: any[]) => Promise<Secret>,
});
@Injectable()
export class SecretService {
  // To make calls for connected accounts, we should create a new Stripe API instance every time.
  private getSecretResource(stripeAccount: string): Stripe {
    const client = new Stripe(process.env.STRIPE_API_KEY, {
      apiVersion: "2020-08-27",
      stripeAccount,
    });
    return new SecretResource(client);
  }
}

Adding secrets

As we can see above, the Secret Storage needs some preliminary setup, which we do in our SecretService. The StripeResource sets up the find, set, and delete methods on the Stripe Api, and interacts with the Secret Store. Let's implement the addSecret method, so we can actually store our returned token.

import { Stripe } from "stripe";
interface Secret {
  id: string;
  name: string;
  payload: string;
}
@Injectable()
export class SecretService {
  // ...
  async addSecret(
    accountId: string,
    userId: string,
    secretName: string,
    value: string
  ): Promise<Secret | null> {
    return this.getSecretResource(accountId)
      .set({
        "scope[type]": "user",
        "scope[user]": userId,
        name: secretName,
        payload: value,
      })
      .catch((error: any) => {
        this.logger.error(
          `Could not set secret to Stripe Secret Store: ${error.statusCode} - ${error.message}`
        );
        return null;
      });
  }
}

With the above, we can finally store our token with which we can make authenticated requests.

Getting secrets

Let's implement the getSecret so we can retrieve secrets. The principles are the same. We will need the accountId, the userId, and the secret's name for it.

import { Stripe } from "stripe";
interface Secret {
  id: string;
  name: string;
  payload: string;
}
@Injectable()
export class SecretService {
  // ...
  async getSecret(
    accountId: string,
    userId: string,
    secretName: string
  ): Promise<Secret | null> {
    const secret = await this.getSecretResource(accountId)
      .find({
        "scope[type]": "user",
        "scope[user]": userId,
        name: secretName,
        "expand[]": "payload",
      })
      .catch((error: any) => {
        if (error.statusCode === 404) {
          throw new UnauthorizedException();
        } else {
          this.logger.error(
            `Could not get secret from Stripe Secret Store: ${error.statusCode} - ${error.message}`
          );
          return null;
        }
      });
    if (!secret) {
      throw new UnauthorizedException();
    }
    return secret.payload;
  }
}

Let's close the login flow, and implement the final version of the api/oauth/userinfo endpoint.

// ...
const THIRD_PARTY_WHO_AM_I_URL = `${process.env.THIRD_PARTY_URL_BASE}/oauth/whoami`;
@Controller("oauth")
export class OauthController {
  // ...
  constructor(private secretService: SecretService) {}
  @Get("userinfo")
  @UseInterceptors(VerifySignatureInterceptor)
  async getUserInfo(
    @Headers("stripe-account-id") accountId: string,
    @Headers("stripe-user-id") userId: string
  ): Promise<UserInfo> {
    const token = await this.secretService.getSecret(
      accountId,
      userId,
      "access_token"
    );

  const user = await axios
      .get<UserInfo>(THIRD_PARTY_WHO_AM_I_URL, {
        responseType: "json",
        headers: {
          authorization: `Bearer ${token}`,
        },
      })
      .catach(() => {
        throw new UnauthorizedException();
      });
    // We add an extra layer of security by requiring the user to verify their e-mail.
    if (!user.email_verified) {
      throw new UnauthorizedException();
    }
    return user;
  }
}

Deleting secrets

We want our users to have ability to log out from our third-party API as well. That can be achieved by deleting their access_token from the Secret store.

import { Stripe } from "stripe";
// ...
@Injectable()
export class SecretService {
  // ...
  async deleteSecret(
    accountId: string,
    userId: string,
    secretName: string
  ): Promise<boolean> {
    return this.getSecretResource(accountId)
      .delete({
        "scope[type]": "user",
        "scope[user]": userId,
        name: secretName,
      })
      .then(() => true)
      .catch((error: any) => {
        this.logger.error(
          `Could not delete secret from Stripe Secret Store: ${error.statusCode} - ${error.message}`
        );
        return false;
      });
  }
}

The /api/oauth/logout endpoint is going to be a GET request, that will delete the token from the Secret Store.

// ...
@Controller("oauth")
export class OauthController {
  // ...
  @Get("logout")
  @HttpCode(204)
  @UseInterceptors(VerifySignatureInterceptor)
  async deleteToken(
    @Headers("stripe-account-id") accountId: string,
    @Headers("stripe-user-id") userId: string
  ): Promise<boolean> {
    return this.secretService.deleteToken(accountId, userId, "access_token");
  }
}

We can create a SignOutLink that will send the request to our back-end and navigates to the /login page. You can put this component into the footerContent property of your ContextView.

import { LOGOUT_URI } from "../../constants/url.constants";
import { useFetchWithCredentials } from "../../hooks/useFetchWithCredentials";
import { Link } from "@stripe/ui-extension-sdk/ui";
import { useNavigate } from "react-router-dom";
export const SignOutLink = () => {
  const navigate = useNavigate();
  const fetchWithCredentials = useFetchWithCredentials();
  return (
    <Link
      onPress={() => {
        fetchWithCredentials(LOGOUT_URI).then(() => {
          navigate("/logout");
        });
      }}
    >
      Sign out
    </Link>
  );
};

And now we are ready with our authentication setup. When the user opens our app, it will call the /api/oauth/userinfo endpoint. Initially, it will return with a 401 error, and our front-end will navigate to the /login route. When the user presses the Sign in button, it will redirect them to the third-party OAuth page. After they log in, our back-end also redirects them back to their Stripe dashboars where the application will open. The app will call the /api/oauth/userinfo endpoint again. But this time, it will return an actual user information and it routes to the protected route.

To help visualize the whole flow, you can also use the following sequence diagram for reference:

Conclusion

As you can see, there are many steps involved in setting up a proper OAuth flow. However, it's necessary to make it right, since this is the most critical part of the app. We hope blog post article will help you to set up some good foundations when implementing your own Stripe app.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Balázs Tápai
He is a Software Engineer with a passion for automated testing. He loves Angular on the Front-End and NestJS on the Back-End. He also uses Cypress to reduce developer anxiety before demo meetings.
@TapaiBalazs @TapaiBalazs
Dario Djuric
Dario is a full-stack engineer who has spent most of his career doing enterprise Java projects. He has always had a hidden passion for frontend, though -- and he is now able to pursue that passion at This Dot. He spends most of his free time with his two sons, but occasionally, he manages to squeeze in some casual sports activities such as jogging, cycling, and soccer.
@dario_djuric @dariodjuric

Understanding Vue's Reactive Data

Introduction Web development has always been about creating dynamic experiences. One of the biggest challenges developers face is managing how data changes over time and reflecting these changes in the UI promptly and accurately. This is where Vue.js, one of the most popular JavaScript frameworks, excels with its powerful reactive data system. In this article, we dig into the heart of Vue's reactivity system. We unravel how it perfectly syncs your application UI with the underlying data state, allowing for a seamless user experience. Whether new to Vue or looking to deepen your understanding, this guide will provide a clear and concise overview of Vue's reactivity, empowering you to build more efficient and responsive Vue 3 applications. So, let’s kick off and embark on this journey to decode Vue's reactive data system. What is Vue's Reactive Data? What does it mean for data to be ”'reactive”? In essence, when data is reactive, it means that every time the data changes, all parts of the UI that rely on this data automatically update to reflect these changes. This ensures that the user is always looking at the most current state of the application. At its core, Vue's Reactive Data is like a superpower for your application data. Think of it like a mirror - whatever changes you make in your data, the user interface (UI) reflects these changes instantly, like a mirror reflecting your image. This automatic update feature is what we refer to as “reactivity”. To visualize this concept, let's use an example of a simple Vue application displaying a message on the screen: ` In this application, 'message' is a piece of data that says 'Hello Vue!'. Let's say you change this message to 'Goodbye Vue!' later in your code, like when a button is clicked. ` With Vue's reactivity, when you change your data, the UI automatically updates to 'Goodbye Vue!' instead of 'Hello Vue!'. You don't have to write extra code to make this update happen - Vue's Reactive Data system takes care of it. How does it work? Let's keep the mirror example going. Vue's Reactive Data is the mirror that reflects your data changes in the UI. But how does this mirror know when and what to reflect? That's where Vue's underlying mechanism comes into play. Vue has a behind-the-scenes mechanism that helps it stay alerted to any changes in your data. When you create a reactive data object, Vue doesn't just leave it as it is. Instead, it sends this data object through a transformation process and wraps it up in a Proxy. Proxy objects are powerful and can detect when a property is changed, updated, or deleted. Let's use our previous example: ` Consider our “message” data as a book in a library. Vue places this book (our data) within a special book cover (the Proxy). This book cover is unique - it's embedded with a tracking device that notifies Vue every time someone reads the book (accesses the data) or annotates a page (changes the data). In our example, the reactive function creates a Proxy object that wraps around our state object. When you change the 'message': ` The Proxy notices this (like a built-in alarm going off) and alerts Vue that something has changed. Vue then updates the UI to reflect this change. Let’s look deeper into what Vue is doing for us and how it transforms our object into a Proxy object. You don't have to worry about creating or managing the Proxy; Vue handles everything. ` In the example above, we encapsulate our object, in this case, “state”, converting it into a Proxy object. Note that within the second argument of the Proxy, we have two methods: a getter and a setter. The getter method is straightforward: it merely returns the value, which in this instance is “state.message” equating to 'Hello Vue!' Meanwhile, the setter method comes into play when a new value is assigned, as in the case of “state.message = ‘Hey young padawan!’”. Here, “value” becomes our new 'Hey young padawan!', prompting the property to update. This action, in turn, triggers the reactivity system, which subsequently updates the DOM. Venturing Further into the Depths If you have been paying attention to our examples above, you might have noticed that inside the Proxy method, we call the functions track and trigger to run our reactivity. Let’s try to understand a bit more about them. You see, Vue 3 reactivity data is more about Proxy objects. Let’s create a new example: ` In this example, when you click on the button, the message's value changes. This change triggers the effect function to run, as it's actively listening for any changes in its dependencies. How does the effect property know when to be called? Vue 3 has three main functions to run our reactivity: effect, track, and trigger. The effect function is like our supervisor. It steps in and takes action when our data changes – similar to our effect method, we will dive in more later. Next, we have the track function. It notes down all the important data we need to keep an eye on. In our case, this data would be state.message. Lastly, we've got the trigger function. This one is like our alarm bell. It alerts the effect function whenever our important data (the stuff track is keeping an eye on) changes. In this way, trigger, track, and effect work together to keep our Vue application reacting smoothly to changes in data. Let’s go back to them: ` Tracking (Dependency Collection) Tracking is the process of registering dependencies between reactive objects and the effects that depend on them. When a reactive property is read, it's "tracked" as a dependency of the current running effect. When we execute track(), we essentially store our effects in a Set object. But what exactly is an "effect"? If we revisit our previous example, we see that the effect method must be run whenever any property changes. This action — running the effect method in response to property changes — is what we refer to as an "Effect"! (computed property, watcher, etc.) > Note: We'll outline a basic, high-level overview of what might happen under the hood. Please note that the actual implementation is more complex and optimized, but this should give you an idea of how it works. Let’s see how it works! In our example, we have the following reactive object: ` We need a way to reference the reactive object with its effects. For that, we use a WeakMap. Which type is going to look something like this: ` We are using a WeakMap to set our object state as the target (or key). In the Vue code, they call this object targetMap. Within this targetMap object, our value is an object named depMap of Map type. Here, the keys represent our properties (in our case, that would be message and showSword), and the values correspond to their effects – remember, they are stored in a Set that in Vue 3 we refer to as dep. Huh… It might seem a bit complex, right? Let's make it more straightforward with a visual example: With the above explained, let’s see what this Track method kind of looks like and how it uses this targetMap. This method essentially is doing something like this: ` At this point, you have to be wondering, how does Vue 3 know what activeEffect should run? Vue 3 keeps track of the currently running effect by using a global variable. When an effect is executed, Vue temporarily stores a reference to it in this global variable, allowing the track function to access the currently running effect and associate it with the accessed reactive property. This global variable is called inside Vue as activeEffect. Vue 3 knows which effect is assigned to this global variable by wrapping the effects functions in a method that invokes the effect whenever a dependency changes. And yes, you guessed, that method is our effect method. ` This method behind the scenes is doing something similar to this: ` The handling of activeEffect within Vue's reactivity system is a dance of careful timing, scoping, and context preservation. Let’s go step by step on how this is working all together. When we run our Effect method for the first time, we call the get trap of the Proxy. ` When running the get trap, we have our activeEffect so we can store it as a dependency. ` This coordination ensures that when a reactive property is accessed within an effect, the track function knows which effect is responsible for that access. Trigger Method Our last method makes this Reactive system to be complete. The trigger method looks up the dependencies for the given target and key and re-runs all dependent effects. ` Conclusion Diving into Vue 3's reactivity system has been like unlocking a hidden superpower in my web development toolkit, and honestly, I've had a blast learning about it. From the rudimentary elements of reactive data and instantaneous UI updates to the intricate details involving Proxies, track and trigger functions, and effects, Vue 3's reactivity is an impressively robust framework for building dynamic and responsive applications. In our journey through Vue 3's reactivity, we've uncovered how this framework ensures real-time and precise updates to the UI. We've delved into the use of Proxies to intercept and monitor variable changes and dissected the roles of track and trigger functions, along with the 'effect' method, in facilitating seamless UI updates. Along the way, we've also discovered how Vue ingeniously manages data dependencies through sophisticated data structures like WeakMaps and Sets, offering us a glimpse into its efficient approach to change detection and UI rendering. Whether you're just starting with Vue 3 or an experienced developer looking to level up, understanding this reactivity system is a game-changer. It doesn't just streamline the development process; it enables you to create more interactive, scalable, and maintainable applications. I love Vue 3, and mastering its reactivity system has been enlightening and fun. Thanks for reading, and as always, happy coding!...

Nov 22, 2023

7 mins

VueJavaScriptTypeScriptWeb Development

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

We take accessibility quite seriously here at This Dot because we know it's important. Still, throughout my career, I've seen many projects where accessibility was brushed aside for reasons like "our users don't really use keyboard shortcuts" or "we need to ship fast; we can add accessibility later." The truth is, that "later" often means "never." And it turns out, anyone could break their hand, like I did. I broke my dominant hand and spent four weeks in a cast, effectively rendering it useless and forcing me to work left-handed. I must thus apologize for the misleading title; this post should more accurately be dubbed "second-hand" accessibility insights. The Perspective of a Developer Firstly, it's not the end of the world. I adapted quickly to my temporary disability, which was, for the most part, a minor inconvenience. I had to type with one hand, obviously slower than my usual pace, but isn't a significant part of a software engineer's work focused on thinking? Here's what I did and learned: - I moved my mouse to the left and started using it with my left hand. I adapted quickly, but the experience wasn't as smooth as using my right hand. I could perform most tasks, but I needed to be more careful and precise. - Many actions require holding a key while pressing a mouse button (e.g., visiting links from the IDE), which is hard to do with one hand. - This led me to explore trackpad options. Apart from the Apple Magic Trackpad, choices were limited. As a Windows user (I know, sorry), that wasn't an option for me. I settled for a cheap trackpad from Amazon. A lot of tasks became easier; however, the trackpad eventually malfunctioned, sending me back to the mouse. - I don't know a lot of IDE shortcuts. I realized how much I've been relying on a mouse for my work, subconsciously refusing to learn new keyboard shortcuts (I'll be returning my senior engineer license shortly). So I learned a few new ones, which is good, I guess. - Some keyboard shortcuts are hard to press with one hand. If you find yourself in a similar situation, you may need to remap some of them. - Copilot became my best friend, saving me from a lot of slow typing, although I did have to correct and rewrite many of its suggestions. The Perspective of a User As a developer, I was able to get by and figure things out to be able to work effectively. As a user, however, I got to experience the other side of the coin and really feel the accessibility (or lack thereof) on the web. Here are a few insights I gained: - A lot of websites apparently _tried_ to implement keyboard navigation, but failed miserably. For example, a big e-commerce website I tried to use to shop for the aforementioned trackpad seemed to work fine with keyboard navigation at first, but once I focused on the search field, I found myself unable to tab out from it. When you make the effort to implement keyboard navigation, please make sure it works properly and it doesn't get broken with new changes. I wholeheartedly recommend having e2e tests (e.g. with Playwright) that verify the keyboard navigation works as expected. - A few websites and web apps I tried to use were completely unusable with the keyboard and were designed to be used with a mouse only. - Some sites had elaborate keyboard navigation, with custom keyboard shortcuts for different functionality. That took some time to figure out, and I reckon it's not as intuitive as the designers thought it would be. Once a user learns the shortcuts, however, it could make their life easier, I suppose. - A lot of interactive elements are much smaller than they should be, making it hard to accurately click on them with your weaker hand. Designers, I beg you, please make your buttons bigger. I once worked on an application that had a "gloves mode" for environments where the operators would be using gloves, and I feel like maybe the size we went with for the "gloves mode" should be the standard everywhere, especially as screens get bigger and bigger. - Misclicking is easy, especially using your weaker hand. Be it a mouse click or just hitting an Enter key on accident. Kudos to all the developers who thought about this and implemented a confirmation dialog or other safety measures to prevent users from accidentally deleting or posting something. I've however encountered a few apps that didn't have any of these, and those made me a bit anxious, to be honest. If this is something you haven't thought about when developing an app, please start doing so, you might save someone a lot of trouble. Some Second-Hand Insights I was only a little bit impaired by being temporarily one-handed and it was honestly a big pain. In this post, I've focused on my anecdotal experience as a developer and a user, covering mostly keyboard navigation and mouse usage. I can only imagine how frustrating it must be for visually impaired users, or users with other disabilities, to use the web. I must confess I haven't always been treating accessibility as a priority, but I've certainly learned my lesson. I will try to make sure all the apps I work on are accessible and inclusive, and I will try to test not only the keyboard navigation, ARIA attributes, and other accessibility features, but also the overall experience of using the app with a screen reader. I hope this post will at least plant a little seed in your head that makes you think about what it feels like to be disabled and what would the experience of a disabled person be like using the app you're working on. Conclusion: The Humbling Realities of Accessibility The past few weeks have been an eye-opening journey for me into the world of accessibility, exposing its importance not just in theory but in palpable, daily experiences. My short-term impairment allowed me to peek into a life where simple tasks aren't so simple, and convenient shortcuts are a maze of complications. It has been a humbling experience, but also an illuminating one. As developers and designers, we often get caught in the rush to innovate and to ship, leaving behind essential elements that make technology inclusive and humane. While my temporary disability was an inconvenience, it's permanent for many others. A broken hand made me realize how broken our approach towards accessibility often is. The key takeaway here isn't just a list of accessibility tips; it's an earnest appeal to empathize with your end-users. "Designing for all" is not a checkbox to tick off before a product launch; it's an ongoing commitment to the understanding that everyone interacts with technology differently. When being empathetic and sincerely thinking about accessibility, you never know whose life you could be making easier. After all, disability isn't a special condition; it's a part of the human condition. And if you still think "Our users don't really use keyboard shortcuts" or "We can add accessibility later," remember that you're not just failing a compliance checklist, you're failing real people....

Dec 6, 2023

5 mins

AccessibilityA11yWeb DevelopmentHTML

How to host a full-stack app with AWS CloudFront and Elastic Beanstalk

How to host a full-stack JavaScript app with AWS CloudFront and Elastic Beanstalk Let's imagine that you have finished building your app. You have a Single Page Application (SPA) with a NestJS back-end. You are ready to launch, but what if your app is a hit, and you need to be prepared to serve thousands of users? You might need to scale your API horizontally, which means that to serve traffic, you need to have more instances running behind a load balancer. Serving your front-end using a CDN will also be helpful. In this article, I am going to give you steps on how to set up a scalable distribution in AWS, using S3, CloudFront and Elastic Beanstalk. The NestJS API and the simple front-end are both inside an NX monorepo The sample application For the sake of this tutorial, we have put together a very simple HTML page that tries to reach an API endpoint and a very basic API written in NestJS. The UI The UI code is very simple. There is a "HELLO" button on the UI which when clicked, tries to reach out to the /api/hello endpoint. If there is a response with status code 2xx, it puts an h1 tag with the response contents into the div with the id result. If it errors out, it puts an error message into the same div. ` The API We bootstrap the NestJS app to have the api prefix before every endpoint call. ` We bootstrap it with the AppModule which only has the AppController in it. ` And the AppController sets up two very basic endpoints. We set up a health check on the /api route and our hello endpoint on the /api/hello route. ` Hosting the front-end with S3 and CloudFront To serve the front-end through a CMS, we should first create an S3 bucket. Go to S3 in your AWS account and create a new bucket. Name your new bucket to something meaningful. For example, if this is going to be your production deployment I recommend having -prod in the name so you will be able to see at a glance, that this bucket contains your production front-end and nothing should get deleted accidentally. We go with the defaults for this bucket setting it to the us-east-1 region. Let's set up the bucket to block all public access, because we are going to allow get requests through CloudFront to these files. We don't need bucket versioning enabled, because these files will be deleted every time a new front-end version will be uploaded to this bucket. If we were to enable bucket versioning, old front-end files would be marked as deleted and kept, increasing the storage costs in the long run. Let's use server-side encryption with Amazon S3-managed keys and create the bucket. When the bucket is created, upload the front-end files to the bucket and let's go to the CloudFront service and create a distribution. As the origin domain, choose your S3 bucket. Feel free to change the name for the origin. For Origin access, choose the Origin access control settings (recommended). Create a new Control setting with the defaults. I recommend adding a description to describe this control setting. At the Web Application Firewall (WAF) settings we would recommend enabling security protections, although it has cost implications. For this tutorial, we chose not to enable WAF for this CloudFront distribution. In the Settings section, please choose the Price class that best fits you. If you have a domain and an SSL certificate you can set those up for this distribution, but you can do that later as well. As the Default root object, please provide index.html and create the distribution. When you have created the distribution, you should see a warning at the top of the page. Copy the policy and go to your S3 bucket's Permissions tab. Edit the Bucket policy and paste the policy you just copied, then save it. If you have set up a domain with your CloudFront distribution, you can open that domain and you should be able to see our front-end deployed. If you didn't set up a domain the Details section of your CloudFront distribution contains your distribution domain name. If you click on the "Hello" button on your deployed front-end, it should not be able to reach the /api/hello endpoint and should display an error message on the page. Hosting the API in Elastic Beanstalk Elastic beanstalk prerequisites For our NestJS API to run in Elastic Beanstalk, we need some additional setup. Inside the apps/api/src folder, let's create a Procfile with the contents: web: node main.js. Then open the apps/api/project.json and under the build configuration, extend the production build setup with the following (I only ) ` The above settings will make sure that when we build the API with a production configuration, it will generate a package.json and a package-lock.json near the output file main.js. To have a production-ready API, we set up a script in the package.json file of the repository. Running this will create a dist/apps/api and a dist/apps/frontend folder with the necessary files. ` After running the script, zip the production-ready api folder so we can upload it to Elastic Beanstalk later. ` Creating the Elastic Beanstalk Environment Let's open the Elastic Beanstalk service in the AWS console. And create an application. An application is a logical grouping of several environments. We usually put our development, staging and production environments under the same application name. The first time you are going to create an application you will need to create an environment as well. We are creating a Web server environment. Provide your application's name in the Application information section. You could also provide some unique tags for your convenience. In the Environment information section please provide information on your environment. Leave the Domain field blank for an autogenerated value. When setting up the platform, we are going to use the Managed Node.js platform with version 18 and with the latest platform version. Let's upload our application code, and name the version to indicate that it was built locally. This version label will be displayed on the running environment and when we set up automatic deployments we can validate if the build was successful. As a Preset, let's choose Single instance (free tier eligible) On the next screen configure your service access. For this tutorial, we only create a new service-role. You must select the aws-elasticbeanstalk-ec2-role for the EC2 instance profile. If can't select this role, you should create it in AWS IAM with the AWSElasticBeanstalkWebTier, AWSElasticBeanstalkMulticontainerDocker and the AWSElasticBeanstalkRoleWorkerTier managed permissions. The next step is to set up the VPC. For this tutorial, I chose the default VPC that is already present with my AWS account, but you can create your own VPC and customise it. In the Instance settings section, we want our API to have a public IP address, so it can be reached from the internet, and we can route to it from CloudFront. Select all the instance subnets and availability zones you want to have for your APIs. For now, we are not going to set up a database. We can set it up later in AWS RDS but in this tutorial, we would like to focus on setting up the distribution. Let's move forward Let's configure the instance traffic and scaling. This is where we are going to set up the load balancer. In this tutorial, we are keeping to the defaults, therefore, we add the EC2 instances to the default security group. In the Capacity section we set the Environment type to Load balanced. This will bring up a load balancer for this environment. Let's set it up so that if the traffic is large, AWS can spin up two other instances for us. Please select your preferred tier in the instance types section, We only set this to t3.micro For this tutorial, but you might need to use larger tiers. Configure the Scaling triggers to your needs, we are going to leave them as defaults. Set the load balancer's visibility to the public and use the same subnets that you have used before. At the Load Balancer Type section, choose Application load balancer and select Dedicated for exactly this environment. Let's set up the listeners, to support HTTPS. Add a new listener for the 443 port and connect your SSL certificate that you have set up in CloudFront as well. For the SSL policy choose something that is over TLS 1.2 and connect this port to the default process. Now let's update the default process and set up the health check endpoint. We set up our API to have the health check endpoint at the /api route. Let's modify the default process accordingly and set its port to 8080. For this tutorial, we decided not to enable log file access, but if you need it, please set it up with a separate S3 bucket. At the last step of configuring your Elastic Beanstalk environment, please set up Monitoring, CloudWatch logs and Managed platform updates to your needs. For the sake of this tutorial, we have turned most of these options off. Set up e-mail notifications to your dedicated alert e-mail and select how you would like to do your application deployments. At the end, let's configure the Environment properties. We have set the default process to occupy port 8080, therefore, we need to set up the PORT environment variable to 8080. Review your configuration and then create your environment. It might take a few minutes to set everything up. After the environment's health transitions to OK you can go to AWS EC2 / Load balancers in your web console. If you select the freshly created load balancer, you can copy the DNS name and test if it works by appending /api/hello at the end of it. Connect CloudFront to the API endpoint Let's go back to our CloudFront distribution and select the Origins tab, then create a new origin. Copy your load balancer's URL into the Origin domain field and select HTTPS only protocol if you have set up your SSL certificate previously. If you don't have an SSL certificate set up, you might use HTTP only, but please know that it is not secure and it is especially not recommended in production. We also renamed this origin to API. Leave everything else as default and create a new origin. Under the Behaviors tab, create a new behavior. Set up the path pattern as /api/* and select your newly created API origin. At the Viewer protocol policy select Redirect HTTP to HTTPS and allow all HTTP methods (GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE). For this tutorial, we have left everything else as default, but please select the Cache Policy and Origin request policy that suits you the best. Now if you visit your deployment, when you click on the HELLO button, it should no longer attach an error message to the DOM. --- Now we have a distribution that serves the front-end static files through CloudFront, leveraging caching and CDN, and we have our API behind a load balancer that can scale. But how do we deploy our front-end and back-end automatically when a release is merged to our main branch? For that we are going to leverage AWS CodeBuild and CodePipeline, but in the next blog post. Stay tuned....

Sep 11, 2023

12 mins

NestJSAWSTypeScriptNodeJS

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

How to Set Up OAuth with a Stripe App

Stripe signatures

useFetchWithCredentials hook

Stripe secrets and the Stripe API

Stripe API key

Stripe App Secret

Stripe NodeJS API

NestJS VerifySignatureInterceptor implementation

Set up the userinfo endpoint

Stripe Secret Store

Adding secrets

Getting secrets

Deleting secrets

Conclusion

Balázs Tápai

Dario Djuric

You might also like

Understanding Vue's Reactive Data

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to host a full-stack app with AWS CloudFront and Elastic Beanstalk

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

Understanding Vue's Reactive Data

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to host a full-stack app with AWS CloudFront and Elastic Beanstalk

Introduction to Zod for Data Validation

Stripe signatures

useFetchWithCredentials hook

Stripe secrets and the Stripe API

Stripe API key

Stripe App Secret

Stripe NodeJS API

NestJS VerifySignatureInterceptor implementation

Set up the userinfo endpoint

The Login flow

Stripe Secret Store

Adding secrets

Getting secrets

Deleting secrets

Conclusion

Balázs Tápai

Dario Djuric

Understanding Vue's Reactive Data

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to host a full-stack app with AWS CloudFront and Elastic Beanstalk

Introduction to Zod for Data Validation

Let's innovate together!

Understanding Vue's Reactive Data

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to host a full-stack app with AWS CloudFront and Elastic Beanstalk

Introduction to Zod for Data Validation