Forem: Kurt Lekanger

How to make a serverless webhook for email alerts, using Gatsby Functions

Kurt Lekanger — Thu, 14 Oct 2021 06:50:56 +0000

Using Gatsby Functions, it's easy to make a serverless function that automatically sends out email alerts triggered by an event - in our case when new content is published in Contentful (a headless CMS).

In a series of articles, I have shown how I created a new website for the condominium where I live using React/Gatsby, Chakra UI and Auth0. Read part 1 of the series here: How I built our condos's new web pages with Gatsby and Chakra UI

The main reason why we wanted a website in the first place, was the need for a place to publish new or important information to our residents. However, I quickly realized that it was cumbersome to manually send email to notify residents every time we had published new information in our headless CMS system.

Using Gatsby Functions it's quite easy to make an API that sends an email alert to subscribers. In this article I'll walk you through how I have set up a web hook where Contentful sends a POST request to my email alert API. The API checks if the request is allowed by verifying a secret key, and then fetches a list of all registered users and sends out an email alert to those users that have chosen to receive alerts.

For email I chose to use Sendgrid. I also considered Nodemailer, but Sendgrid has a nice email template feature where my API can fetch URL, article title and excerpt from Contentful, and pass this information along to the email template in Sendgrid. Then the user receiving the email can click on a link in the email to open the article that was just published on the condo's web site.

To make everything work, I had to set up the following:

Create a webhook in Contentful
Make a serverless function (our API) with Gatsby Functions
Create an email template in Sendgrid

What I have made could easily be adapted to other needs or purposes. If you're not using Gatsby, you don't need to make any big changes to make it work with Netlify Functions or Next.js API routes. The code is pretty similar to how you would create this using the Node.js Express framework.

Setting up a webhook in Contentful

All content on the condominium's website is published in the headless CMS solution Contentful. Under the Settings menu in Contentful, you have an option called Webhooks. Here I created a webhook that will be triggered only when new content is published, and then send a POST request to the email API I intend to create.

After clicking Add Webhook and giving the webhook a name, I had to specify that it should be a POST request that will go to the URL of my email API.

Under Content Events I specify that the webhook should be called only when new content has been published.

I don't want everyone to be able to make requests to my API and spam my users with email. So I created a secret header which is a key/value pair that is sent in the header of the API request. A secret key the API will verify before allowing email to be sent.

I called my secret key CONTENTFUL_WEBHOOK_SECRET and used a password generator to make a long password with numbers, letters and special characters.

Create the email API using Gatsby Functions

Gatsby Functions is an Express-like way of building APIs for your Gatsby projects. It's serverless functions, which of course does not mean that you don't need servers, but you don't have to think about the servers. Just focus on writing code - just the way I like it.

To make a new Gatsby Function you create a JavaScript or TypeScript file in the folder /src/api and export a handler function which takes two parameters - req (request) and res (response).

I created a file called email-alert-users.ts in the api/admin-users folder (use .js if you do not use TypeScript). This means that my API endpoint will be https://url-to-my-site-admin/admin-users/email-alert-users.

In the first part of the code, I first check that the HTTP method is POST. Then I check that the header contains CONTENTFUL_WEBHOOK_SECRET and that it matches the secret key I have stored as an environment variable (locally in a .env file, and at Netlify under Deploy Settings and Environment. Make sure you do not submit this to Github - check that you have .env* in your .gitignore file.

Here is the first part of the code, with the necessary checks:

// src/api/admin-users/email-alert-users.ts

import { GatsbyFunctionRequest, GatsbyFunctionResponse } from 'gatsby';
const ManagementClient = require('auth0').ManagementClient;
const sgMail = require('@sendgrid/mail');

export default async function handler(
  req: GatsbyFunctionRequest,
  res: GatsbyFunctionResponse
) {
  if (req.method !== `POST`) {
    return res.status(405).json({
      error: 'method not allowed',
      error_description: 'You should do a POST request to access this',
    });
  }

  // Check if secret key received from Contentful web hook matches the one in the .env file
  if (
    req.headers.contentful_webhook_secret !==
    process.env.CONTENTFUL_WEBHOOK_SECRET
  ) {
    return res.status(401).json({
      error: 'unauthorized',
      error_description: 'The Contentful web hook secret key is not correct',
    });
  }

// ...code continues

If you're not using TypeScript, remove GatsbyFunctionRequest and GatsbyFunctionResponse, this is just for type checking.

At the top I import ManagementClient to be able to connect to Auth0's Management API, so that I can fetch a list of all users who should receive email. You can of course get this user list from other places as well, such as a database.

Set up the email contents

The emails should contain the following, in addition to a standard text stating that there is new content (I set this up at Sendgrid):

Title and introduction
URL of the article

Some of the content on the condominiums website is only available to logged in users, using client-only routes in my Gatsby project, more specifically under the route /information. All open articles are under /blog. This means that I must first check if it is a private article or not, and then build the correct URL based on this. When the Contentful webhook makes a POST request to my API, it passes on lots of info about what is published in the body of the request. I have created a field in Contentful called privatePost that can be set to true or false (this is a checkbox you tick when you write an article in the Contentful editor). This makes it easy to create the correct URL by letting the API check this field first.

I also retrieve the article title and excerpt (short intro about the article) in this way:

// src/api/admin-users/email-alert-users.ts

  let articleURL;
  if (req.body.fields.privatePost.nb === true) {
    articleURL = `https://gartnerihagen-askim.no/informasjon/post/${req.body.fields.slug.nb}/${req.body.sys.id}`;
  } else {
    articleURL = `https://gartnerihagen-askim.no/blog/${req.body.fields.slug}/${req.body.sys.id}`;
  }

  const articleTitle = req.body.fields.title.nb;
  const articleExcerpt = req.body.fields.excerpt.nb;

// ...code continues

Get all email subscribers

Now that the email content has been retrieved, I connect to Auth0's Management API and request the permission ("scope") read:users. Then I use the getUsers() method to fetch all the users. Then I use a combination of .filter and .map to create a list of only users who have subscribed to email. I have stored this information in the user_metadata field for each user in Auth0.

I now have a list of all users who want email. I use sgMail.setApiKey(process.env.SENDGRID_API_KEY) to send an API key to access my Sendgrid account. Then I set up the email content and store it in the msg constant. msg contains an array of email recipients, the sender's email address, and a templateId. The latter is the ID of an email template I have set up at Sendgrid. Under dynamic_template_data I can pass along information about the article URL, title and excerpt of the article, which will then be captured by Sendgrid and filled out in the email template.

Finally, the email is sent with sgMail.sendMultiple (msg).

// src/api/admin-users/email-alert-users.ts

// Connect to the Auth0 management API
  const auth0 = new ManagementClient({
    domain: `${process.env.GATSBY_AUTH0_DOMAIN}`,
    clientId: `${process.env.AUTH0_BACKEND_CLIENT_ID}`,
    clientSecret: `${process.env.AUTH0_BACKEND_CLIENT_SECRET}`,
    scope: 'read:users',
  });

  try {
    const users = await auth0.getUsers();

    // Filter out only those users that have subscribed to email alerts
    // This is defined in the user_metadata field on Auth0
    const userEmails = users
      .filter((user) => {
        return (
          user &&
          user.user_metadata &&
          user.user_metadata.subscribeToEmails === true
        );
      })
      .map((user) => user.email);

    // using Twilio SendGrid's v3 Node.js Library
    // https://github.com/sendgrid/sendgrid-nodejs
    sgMail.setApiKey(process.env.SENDGRID_API_KEY);

    const msg = {
      to: userEmails,
      from: 'Boligsameiet Gartnerihagen <post@gartnerihagen-askim.no>',
      templateId: 'd-123456789',  // The ID of the dynamic Sendgrid template
      dynamic_template_data: {
        articleURL,
        articleTitle,
        articleExcerpt,
      },
    };

    await sgMail.sendMultiple(msg);

// ...code continues

If everything has worked as expected, I return status 200 and some info. I do everything inside a try/catch block, and in case of an error I return an error code.

res.status(200).json({
      body: {
        status_code: 200,
        status_description: 'Emails are sent to all subscribed users',
        userEmails,
      },
    });
  } catch (error) {
    res.status(error.statusCode).json({
      error: error.name,
      message: error.message,
      status_code: error.statusCode || 500,
      error_description: error.message,
    });
  }
}

Configuring the Sendgrid email template

I could of course "hard code" the email contents, but with "dynamic Templates" in Sendgrid you can customize the email with the information you want. In my case information about the article that was published, including an URL.

To set up a dynamic email template in Sendgrid, go to sendgrid.com, log in and select Email API → Dynamic Templates from the settings menu. Then tap Create a Dynamic Template, then Add Version. You can now choose to use Sendgrid's design editor to design your email, or you can use an HTML editor. I used the HTML editor and added some standard text.

To insert dynamic content in the text - such as title or URL- you can use variable names. In my email API, I use the variable name articleTitle for the article title I receive from my CMS. To use this variable in the Sendgrid template, just insert {{articleTitle}} into the HTML code.

On the right hand side (see screenshot below) you can see what the email will look like. If you press Test Data in the menu at the top, you can enter test data for the various variables you use in the email template to check that everything looks OK.

That's it! We now have created an email alert service that sends out an email every time new content is published in our headless CMS.

I also updated the user admin dashboard for our web pages, so that admins can turn on or off email alerts for users. The users are also able to do this by themself on their "My page" when logged in:

The source code for this project is on my Github. If you're just interested in the email alert Gatsby Function, you'll find it here.

In this article you can read about how I made a user admin dashboard with Gatsby Functions and Auth0

This is a translation, original article is published on my personal web site lekanger.no

Part 6: User admin dashboard with Gatsby Functions: Update, create and delete users

Kurt Lekanger — Sun, 12 Sep 2021 13:35:35 +0000

In a series of articles, I have shown how I created a new website for the condominium association where I live using Gatsby and with Auth0 user authentication. Read part 1 here: How I built our condos's new web pages with Gatsby and Chakra UI

In my previous article I showed how I built a user admin dashboard with Gatsby Functions, and I configured everything at Auth0 so that I could use role-based access control and Auth0s Management API to display a list of everyone who is registered as a user on the condominium's website, gartnerihagen-askim.no.

The functionality for displaying all users, including what roles they have (user, editor or admin) is finished. Now we need to build the functionality for creating, updating or deleting users.

Create new users

When the user clicks the Create New User button ("Opprett ny bruker" in the screenshot below), I use Gatsby's navigate helper function to send the user to /user-admin/create-user.

The route /user-admin/ and everything below is configured as a client only route in the plugin gatsby-plugin-create-client-paths in the file gatsby-config.js, so that no static pages are created when building the Gatsby site. Under /src/pages I have created the file user-admin.tsx which contains the necessary code to route users to the pages for creating users, updating users, or go to the main page for user administration. The <Privateroute> component in the code snippet below uses a higher order component in auth0-react called withAutenthicationRequired to check if a user is logged in or not.

// src/pages/user-admin.tsx

import * as React from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { Router } from '@reach/router';
import PrivateRoute from '../utils/privateRoute';
import NotLoggedIn from '../components/notLoggedIn';
import LoadingSpinner from '../components/loading-spinner';
import UserAdminPage from '../components/private-components/user-admin/userAdminPage';
import CreateUserPage from '../components/private-components/user-admin/createUserPage';
import UpdateUserPage from '../components/private-components/user-admin/updateUserPage';

function UserAdmin() {
  const { isLoading, isAuthenticated, error } = useAuth0();

  if (isLoading) {
    return <LoadingSpinner />;
  }

  if (error) {
    return <div>Det har oppstått en feil... {error.message}</div>;
  }

  if (!isAuthenticated) {
    return (
      <NotLoggedIn
        title='Logg inn for brukeradministrasjon'
        description='Du må logge inn for å administrere brukerkontoer for Boligsameiet Gartnerihagen. 
      Du vil da kunne legge til, slette eller endre brukere, samt gi brukere admin-tilgang.
      Ta kontakt med styret.'
        redirectUser='/user-admin'
      />
    );
  }

  return (
    <Router>
      <PrivateRoute path='/user-admin/create-user' component={CreateUserPage} />
      <PrivateRoute path='/user-admin/update-user' component={UpdateUserPage} />
      <PrivateRoute path='/user-admin' component={UserAdminPage} />
    </Router>
  );
}

export default UserAdmin;

If the user is logged in, we render the component createUserPage.tsx and the user will see this on the screen ("Create a new user"):

With Chakra UI it is easy to make a form that looks nice. React's useState hook is used for storing the state of the form. All data that is entered into the form is stored in the variable formData, as an object with key/value pairs for email, name, and so on:

const [formData, setFormData] = useState({
    email: '',
    name: '',
    password: '',
    repeatPassword: '',
    roles: [],
});

When someone changes the information in one of the fields of the form, I use setFormData to update the state of the form so that formData at all times contains the correct information. For example, this is how I update the surname ("fornavn") and last name ("etternavn") fields:

  <FormControl id='name' isRequired>
    <FormLabel>Fornavn og etternavn</FormLabel>
    <Input
      value={formData.name}
      placeholder='Fornavn Etternavn'
      onChange={(e) =>
        setFormData((prevState) => {
          return {
            ...prevState,
            name: e.target.value,
          };
        })
      }
    />
  </FormControl>

FormControl in the code snippet above comes from Chakra UI and gives a little extra control when using forms, you can read more about it here.

If the user changes the contents of the field (onChange), we use the spread operator to fill in all existing data in formData with ...formData, and then we change formData.name to whatever the field contains.

When the user presses the Create button, we call the handleSubmit function. In this function we start by validating the information entered in the fields. I check if both password fields are identical, and that the password entered contains both numbers and uppercase and lowercase letters, and that the password is at least 8 characters long:

const handleSubmit = async (event) => {
    event.preventDefault();

    if (formData.password !== formData.repeatPassword) {
      toast({
        title: 'Passordene er ikke like',
        description:
          'Pass på at du har skrevet passordet helt likt i de to feltene.',
        status: 'error',
        duration: 3000,
        isClosable: true,
      });
      return;
    }

    if (!formData.password.match(/((?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,})/)) {
      toast({
        title: 'Ikke sterkt nok passord',
        description:
          'Passordet må inneholde både tall og store og små bokstaver, og være minst 8 tegn langt.',
        status: 'warning',
        duration: 3000,
        isClosable: true,
      });
      return;
    }

// ...the rest of the handleSubmit function

If the passwords are not identical, or not strong enough, I use the Toast component in Chakra UI to display a warning that pops up on the screen for a few seconds, before disappearing again.

The new user form also have checkboxes for which roles the new user will have. I store whether or not the checkboxes are checked in the variables isAdminChecked and isEditorChecked. Then I can do the following in the handleSubmit function to update the roles array in formData with all the roles we want the new user to have:

formData.roles = ['user'];
if (isAdminChecked) {
  formData.roles.push('admin');
}
if (isEditorChecked) {
  formData.roles.push('editor');
}

All users should have the role "user", so we only have to check for admin and editor. We add the role "user" to all newly created users.

Contact our serverless function to create the user

We have now updated our formData variable so that it contains a Javascript object with all necessary data about the user we want to create. Example of what formData can look like when we press the "Create" button:

{
    email: 'ola@nordmann.no',
    name: 'Ola Nordmann',
    password: 'InnmariBraPassord123',
    repeatPassword: 'InnmariBraPassord123',
    roles: ['user', 'admin'],
}

Now we can make a request to our create-user API that we have made with Gatsby Functions. All t Functions are located in /src/api/. Here's how it's done on the client (we are still in our handleSubmit function in the createUserPage component at the client:

try {
      const accessToken = await getAccessTokenSilently(opts);
      const api = await fetch(`/api/admin-users/create-user`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${accessToken}`,
        },

        body: JSON.stringify(formData),
      });

      if (api?.status !== 200) {
        throw new Error(`${api.statusText} (${api.status})`);
      }

      const isJson = api.headers
        .get('content-type')
        ?.includes('application/json');

      const data = isJson && (await api.json());

      if (!data) {
        throw new Error('no_data');
      }

      if (data.error) {
        const { error_description } = JSON.parse(data?.error_description);
        throw new Error(`${data.error} : ${JSON.stringify(error_description)}`);
      }

      // Store the API response (e.g. the user data for the newly created user)
      setResponse(data?.body?.user);

      setShowLoadingButton(false);
    } catch (error) {
      if (
        error.message.includes(
          'Consent required' || 'Forbidden (403)' || 'access_denied'
        )
      ) {
        getToken();
      }

      if (error.message === 'Conflict (409)') {
        toast({
          title: 'Brukeren eksistererer allerede',
          description:
            'Hver bruker må ha en unik epost-adresse og et unikt navn.',
          status: 'error',
          duration: 3000,
          isClosable: true,
        });
      } else {
        toast({
          title: 'Noe gikk galt',
          description: `${error.message}`,
          status: 'error',
          duration: 3000,
          isClosable: true,
        });
      }
      setResponse(null);
      setShowLoadingButton(false);
    }

Let's start at the top: First we fetch the user's access token from Auth0 with getAccessTokenSilently(opts). opts are configured like this:

const opts = {
    audience: 'https://useradmin.gartnerihagen-askim.no',
    scope: 'create:users read:roles create:role_members',
  };

Scope are which permissions the user should have to be able to create another user, and the user should also request permissions for updating the roles of the newly created user. For more information, have a look at Auth0's documentation on how to call a protected API with an access token here.

We have now received an access token that we can include in the authorization header when calling our create-user API. In addition to the token, we also include our formData - data about the user we want to create - in body, like this:

const api = await fetch(`/api/admin-users/create-user`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },

    body: JSON.stringify(formData),
});

Our Gatsby Function for creating users

Our serverless function create-user will now receive a POST request where the access token is in the authorization header and info about the user to be created is in the body.

Before we call Auth0's Management API to create the user, it's a good idea to do some checking. I use the @serverless-jwt/jwt-verifier library to read the access token received from the client, and then I use jwt.verifyAccessToken to check that it is a valid token. I also retrieve all the permissions (scopes) from the access token, and check that the user has the permissions needed for creating a user. I only check for the scope create:users. If the user can create users, the user should also be able to read roles and assign roles to users - we don't need to verify that.

Here is the first part of our serverless function:

// src/api/admin-users/create-user.ts

import { GatsbyFunctionRequest, GatsbyFunctionResponse } from 'gatsby';
const ManagementClient = require('auth0').ManagementClient;
const {
  JwtVerifier,
  JwtVerifierError,
  getTokenFromHeader,
} = require('@serverless-jwt/jwt-verifier');

const ALLOWED_ROLES = ['user', 'admin', 'editor'];

const jwt = new JwtVerifier({
  issuer: `https://${process.env.GATSBY_AUTH0_DOMAIN}/`,
  audience: `https://${process.env.AUTH0_USERADMIN_AUDIENCE}`,
});

export default async function handler(
  req: GatsbyFunctionRequest,
  res: GatsbyFunctionResponse
) {
  let claims, permissions;
  const token = getTokenFromHeader(req.headers.authorization);
  const userRoles = req.body.roles;

  if (req.method !== `POST`) {
    return res.status(405).json({
      error: 'method not allowed',
      error_description: 'You should do a POST request to access this',
    });
  }

  userRoles.forEach((role) => {
    if (!ALLOWED_ROLES.includes(role)) {
      return res.status(403).json({
        error: 'invalid user role',
        error_description: 'Serveren mottok en ugyldig brukerrolle',
      });
    }
  });

  // Verify access token
  try {
    claims = await jwt.verifyAccessToken(token);
    permissions = claims.permissions || [];
  } catch (err) {
    if (err instanceof JwtVerifierError) {
      return res.status(403).json({
        error: `Something went wrong. ${err.code}`,
        error_description: `${err.message}`,
      });
    }
  }

  // check if user should have access at all
  if (!claims || !claims.scope) {
    return res.status(403).json({
      error: 'access denied',
      error_description: 'You do not have access to this',
    });
  }

  // Check the permissions
  if (!permissions.includes('create:users')) {
    return res.status(403).json({
      error: 'no create access',
      status_code: res.statusCode,
      error_description:
        'Du må ha admin-tilgang for å opprette brukere. Ta kontakt med styret.',
      body: {
        data: [],
      },
    });
  }

// ...create-user.ts continous

If the user passes all checks, we're ready to create the new user. Vi create a new Auth0 ManagementClient:

const auth0 = new ManagementClient({
  domain: `${process.env.GATSBY_AUTH0_DOMAIN}`,
  clientId: `${process.env.AUTH0_BACKEND_CLIENT_ID}`,
  clientSecret: `${process.env.AUTH0_BACKEND_CLIENT_SECRET}`,
  scope: 'create:users read:roles create:role_members',
});

Then we create a new constant, userData that holds an object with data about the user - which we get from req.body. connection in the code snippet below is the name of the Auth0 database where we store all the users:

const userData = {
  connection: 'Username-Password-Authentication',
  email: req.body.email,
  name: req.body.name,
  password: req.body.password,
  verify_email: false,
  email_verified: false,
};

Now we can create the user with the createUser method from the Auth0 Management API SDK (we're putting everything inside a try/catch block to get error handling):

const newUser = await auth0.createUser(userData);

Unless something goes wrong, Auth0 has now created the user for us and added it to the Username-Password-Authentication database on their servers. However, we're not quite finished yet. We need to give the new user the roles we selected when filling out the add user form on the client. For that, we need a couple of other methods from the Auth0 Management API: getRoles to fetch all roles defined at Auth0, and assignRolesToUser to assign the roles to our new user:

const allRoles = await auth0.getRoles();
let rolesToAdd = [];
allRoles.forEach((role) => {
  if (userRoles.includes(role.name)) {
    rolesToAdd.push(role.id);
  }
});
await auth0.assignRolestoUser(
  {
    id: newUser.user_id,
  },
  {
    roles: rolesToAdd,
  }
);

In the code snippet above, we first fetch all roles with getRoles and store this in the constant allRoles. Then we create a new, empty array called rolesToAdd that eventually will contain all the roles we want to assign to the user. We then use forEach to iterate over all the roles we have defined at Auth0 and check if the role excists in userRoles (which we fetch from req.body.roles in the start of our code). If the role excists, we add the role to the rolesToAdd array. Note that we have to use the ID and not the name of the role, as this is what's required by the assignRolesToUser method.

When the rolesToAdd array has all the role IDs the user should have, we call assignRolesToUser with the ID of the new user (which we got when we called createUser) and the array with all the roles we want to assign to the user).

If everything have worked out as expected, we return the new user and the roles back to the client - just to confirm that the user has been created:

res.status(200).json({
    body: {
      status_code: 200,
      status_description: 'Ny bruker er opprettet',
      user: { ...newUser, roles: userRoles },
    },
  });

Confirm that the user has been created

When the client (ie the <CreateUserPage> component) receives the response from the API, I first check that the HTTP status code is 200, which indicates that everything is OK. I do this inside a try/catch block, to be able to use throw new Error() and handle the error in the catch block (I use the Toast component in Chakra UI to display a sensible error message).

If all went well, I receive data about the new user from the API, and I use the useState hook in React to store data about the user in the response variable, like so: setResponse(data?.Body?.User)

Finally, I use a modal component in Chakra UI to display a confirmation that the user has been created, with the user information we just received from the API:

Updating a user

Updating users is not very different. When we click the Create User button on one of the users in the user admin dashboard, we navigate to the route /user-admin/update-user with Gatsby's navigate helper function. We also send data about the user we want to change, by passing in an options object to the navigate function, with a state prop inside. This is from the component in userAdminPage.tsx:

onClick={() =>
    navigate('/user-admin/update-user', {
      state: userToShow,
    })
}

If the user is authenticated, the component UpdateUserPage is rendered - this is controlled by Reach Router which is built into Gatsby. We get access to the user data via props.location.state like this: const userToModify = props?.location?.state.

Then I use the useState hook in React to store the current state of the user information for the user I'm updating in an object (userDataForm):

const [userDataForm, setUserDataForm] = useState({
    created_at: '',
    last_login: '',
    email: '',
    name: '',
    picture: '',
    roles: [],
    user_id: '',
  });

The first time the component is rendered, I set userDataForm to the user data we just received via props.location.state:

useEffect(() => {
  setUserDataForm({
    ...userToModify,
    roles: [...userToModify.roles],
  });
}, []);

I won't go into all the details about everything I do on the client to update the user information, it's basically just pre-filling a form with info about the user we are going to edit, and then in case of changes to any of the fields in the form use setUserDataForm to update state (much like we did in the new user creation form). This is the screen you get when you press Change user:

The source code of the component UpdateUserPage is on my Github, together with the rest of the source code.

Call the serverless function to update the user

I created a handleSubmit function which runs when we press the "Update" button in the form. handleSubmit first fetches the access token of the logged in user, and I specify that the user needs the permissions update:users, read:roles and create:role_members. Then we make a PATCH request to our serverless Gatsby Function update-user, and pass along the access token in the authentication header and the updated data about the user (userDataForm) in body:

// src/components/private-components/user-admin/updateUserPage.tsx

const opts = {
  audience: 'https://useradmin.gartnerihagen-askim.no',
  scope: 'update:users read:roles create:role_members',
};

try {
      const accessToken = await getAccessTokenSilently(opts);
      const api = await fetch(`/api/admin-users/update-user`, {
        method: 'PATCH',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${accessToken}`,
        },

        body: JSON.stringify(userDataForm),
      });

// ...the rest of the code

How the update user serverless function works

In the Gatsby function update-user located in our API directory, we do much of the same as we did when we were creating a user. We verify the access token and check that the client calling the API has the necessary permissions. Then we use the Auth0s Management API SDK to create a new ManagementClient which we call auth0, and then we can call auth0.updateUser() to update the user. updateUser() requires the ID of the user you want to update, along with the updated user data:

// src/api/admin-users/update-user.ts

const updatedUser = await auth0.updateUser(
  { id: req.body.user_id },
  userData
);

We also need to add and/or remove roles from the user. I create an empty array I call rolesToRemove and another I call rolesToAdd. Then I loop over all the roles defined in Auth0, and see if the roles exist or not in the user data, and use auth0.assignRolesToUser and auth0.removeRolesFromUser, respectively, to add or remove roles. Finally, the API returns info about the updated user and which roles have been removed or added. If something goes wrong (for example, if the Auth0s Management API complains about something), this is intercepted by the catch block - which returns information about the error to the client. If this happens, I use the Toast component in Chakra UI to give a hopefully meaningful error message to the user.

Here is the rest of the backend code that updates the user and the roles of the user:

// src/api/admin-users/update-user.ts

  const auth0 = new ManagementClient({
    domain: `${process.env.GATSBY_AUTH0_DOMAIN}`,
    clientId: `${process.env.AUTH0_BACKEND_CLIENT_ID}`,
    clientSecret: `${process.env.AUTH0_BACKEND_CLIENT_SECRET}`,
    scope: 'update:users read:roles create:role_members',
  });

  const userData = {
    connection: 'Username-Password-Authentication',
    email: req.body.email,
    name: req.body.name,
  };

  try {
    const updatedUser = await auth0.updateUser(
      { id: req.body.user_id },
      userData
    );
    const allRoles = await auth0.getRoles();

    let rolesToRemove = [];
    allRoles.forEach((role) => {
      if (!userRoles.includes(role.name)) {
        rolesToRemove.push(role.id);
      }
    });

    let rolesToAdd = [];
    allRoles.forEach((role) => {
      if (userRoles.includes(role.name)) {
        rolesToAdd.push(role.id);
      }
    });

    if (rolesToAdd.length > 0) {
      await auth0.assignRolestoUser(
        {
          id: req.body.user_id,
        },
        {
          roles: rolesToAdd,
        }
      );
    }

    if (rolesToRemove.length > 0) {
      await auth0.removeRolesFromUser(
        {
          id: req.body.user_id,
        },
        {
          roles: rolesToRemove,
        }
      );
    }

    res.status(200).json({
      body: {
        status_code: 200,
        status_description: 'Bruker er oppdatert',
        user: updatedUser,
        roles_removed: rolesToRemove,
        roles_added: rolesToAdd,
      },
    });
  } catch (error) {
    res.status(error.statusCode).json({
      error: error.name,
      status_code: error.statusCode || 500,
      error_description: error.message,
    });
  }

Deleting users

Deleting a user is done in a similar way. If someone clicks the Delete User button on the client, I store the user ID and the name of the user in a constant, userToDelete, and show a warning with the AlertDialog component in Chakra UI.

If you confirm that you are sure you want to delete the user, I call my function handleDeleteUser which in turn fetches the access token of the logged-in user and asks Auth0 for the delete:user permission. I then do a DELETE request to our serverless function delete-user with the access token in the authorization header and the userToDelete constant in the body of the request:

const handleDeleteUser = async () => {
    const opts = {
      audience: 'https://useradmin.gartnerihagen-askim.no',
      scope: 'delete:users',
    };

    try {
      if (!userToDelete.id.includes('auth0')) {
        throw new Error('User ID is not valid');
      }

      const accessToken = await getAccessTokenSilently(opts);
      const api = await fetch(`/api/admin-users/delete-user`, {
        method: 'DELETE',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${accessToken}`,
        },

        body: JSON.stringify({ idToDelete: userToDelete.id }),
      });

// ... the rest of the code

Our API (serverless function) for deleting users then checks the validity of the access token, and of course that the user has the permissions to delete other users. We also check that the user ID in req.body.idToDelete is valid. If it is, then we create a new Auth0 ManagementClient which we call auth0, and call auth0.deleteUser() like this:

// src/api/admin-users/delete-user.ts

.
.
.

const auth0 = new ManagementClient({
    domain: `${process.env.GATSBY_AUTH0_DOMAIN}`,
    clientId: `${process.env.AUTH0_BACKEND_CLIENT_ID}`,
    clientSecret: `${process.env.AUTH0_BACKEND_CLIENT_SECRET}`,
    scope: 'delete:users',
  });

  try {
    const idToDelete = req.body.idToDelete;

    if (!idToDelete || !idToDelete.includes('auth0')) {
      const error = {
        name: 'bad user id',
        statusCode: 400,
        message: 'Manglende bruker-id eller feil format',
      };
      throw error;
    }

    await auth0.deleteUser({ id: idToDelete });

    res.status(200).json({
      body: {
        status_code: 200,
        status_description: 'Bruker er slettet',
      },
    });
  } catch (error) {
    res.status(error.statusCode || 500).json({
      error: error.name,
      status_code: error.statusCode || 500,
      error_description: error.message,
    });
  }

If everything is successful, we return HTTP status code 200 to the client and use Chakra UIs Toast component to show an alert that the user has been deleted.

Some final thoughts

Pooh! This was a lot of work, but after some late evenings and weekends with coding I was able to finish our condominiums web page, with user administration and most of the features we need.

I have not gone into detail on all the nooks and crannies of how everything is built, but instead I encourage you to take a look at the complete source code on my Github.

When I started the job of creating the web site, I thought that this should be done fairly quickly - but if there is one thing I have learned from the project, it is that a web site like this is never finished. There is always something that can be improved.

I will probably spend some refactoring and improving the code to make things a little tidier, and then the plan is also to create a serverless function that automatically notifies registered users when new content is published. Here I will set up a webhook at Contentful that calls a Gatsby Function that uses Sendgrid's node solution to send an email with a link to the new content. Or perhaps I just use Nodemailer.

If you have any feedback or thoughts on the project, or suggestions for things that can be improved, feel free to comment. I'm not a professional developer and has done all this in my spare time, mostly weekends and evenings. So I'm thankful for all constructive inputs on things that could be improved.

You can find all the source code at https://github.com/klekanger/gartnerihagen

This YouTube video shows what the user interface and web pages look like live:

This is a translation, the original article in Norwegian is here: Brukeradmin-dashbord med Gatsby Functions: Oppdatere, opprette eller slette brukere

Part 5: Making a user admin dashboard with Gatsby Functions and Auth0

Kurt Lekanger — Sun, 12 Sep 2021 13:35:26 +0000

When the new website was launched, all user administration was done via a technical and complicated user interface at Auth0. For the condominium's website to be a full-fledged solution that can be handed over to non-technical users, a more user-friendly dashboard was needed. It should be possible for non-technical users to create, update or delete users and do all the admin tasks without contacting me.

This is how I built the user admin solution:

*Gatsby on the frontend to create the user admin dashboard. For the dashboard I use client-only routes in Gatsby, which I have written about here.
Auth0 Authentication API for frontend user authentication. Here I use the Auth0 React SDK for Single Page Apps to make things a little easier for myself.
Gatsby Functions (serverless functions) on the backend. These are Node applications running on the server that contact the Auth0 Management API to create, update, or delete users.

You can find the source code for the site at https://github.com/klekanger/gartnerihagen, but in this article I want to go through how I have structured everything - without going into all the details (that would make a book!).

Securing everything

Everything on the client (i.e. in the browser) can be manipulated. Building a user administration dashboard requires a high level of security, and authenticating users and verifying that the user has permission to create, delete or update other users should therefore be done on a server - not on the client.

This is how my solution works:

The user logs in to the client and receives an access token from Auth0
When the user visits the user admin dashboard, the access token is sent to a serverless function at Netlify which 1) checks that it is a valid access token, 2) contacts Auth0 and checks that the access token belongs to a user with the necessary permissions to do whatever she or he tries to do
If the user has all required permissions, the serverless function contacts Auth0's Management API which for example returns a list of all users.

To access the user admin dashboard on the web page, the user must have the role "admin". I use Auth0's role-based access control (RBAC) to define three different roles: "user", "editor" and "admin". Depending on the role, the logged in user will see buttons for user administration or content editing:
Buttons for user admin and content editing will appear on the user's "My page" if the user has the required roles.

This is a simplified diagram showing how this works:

Gatsby Functions makes it easy to create APIs

When I began creating the user admin dashboard, I started creating the APIs to retrieve, update or create users using Netlify Functions. But then Gatsby announced Gatsby Functions, so I decided to convert my Netlify functions into Gatsby Functions (which was quite easy, they are not that different). With built-in support for serverless functions in Gatsby, my job became even easier. This is something Next.js has had for a long time, so it was about time, Gatsby!

Creating a Gatsby Function is as simple as creating a JavaScript or TypeScript file in the src/api folder and exporting a handler function that takes two parameters - req (request) and res (response). For those who have used the Node framework Express, Gatsby Functions is pretty similar.

The Hello World example in Gatsby's official documentation illustrates how easy it is to make a serverless function API with Gatsby Functions:

// src/api/hello-world.js

export default function handler(req, res) {
  res.status(200).json({ hello: `world` })
}

If you make a request to the URL /api/hello-world the serverless function will return { hello: 'world' } and the HTTP status code 200 (which means everything is OK).

Four APIs

I decided that I needed four API-s to create my user admin dashboard. Each API is one servierless function:

src
├── api
│   └── admin-users
│       ├── create-user.ts
│       ├── delete-user.ts
│       ├── get-users-in-role.ts
        └── update-user.ts

When the user visits the user admin web page via "My page", we call the API admin-users/get-users-in-role. If the user have the required permissions the API returns a list over every user, including the role of each user. Each user is displayed as a "user card" in the user admin dashboard, with buttons for changing the user, deleting a user, or changing the user's password:

A search field and a dropdown menu let's you filter out the users you want to see.

Auth0 configuration

Before I could create my own backend APIs for user administration with Gatsby Functions, I had to configure some things in Auth0.

First I had to create a new so-called machine-to-machine application at Auth0. These are applications that will not communicate with clients, but with another server you trust (like the serverless functions I will create for user administration).

When I log in to manage.auth0.com and go to Applications, I have these two applications:

The one named Boligsameiet Gartnerihagen takes care of authentication for users who are logged in to the website. The one called Backend is the machine-to-machine application to be used by our serverless Gatsby function running on Netlify's servers.

To set up role-based access control (RBAC), we must create a new API at Auth0 where we define all the permissions (scopes) we want to be able to give users based on which roles the user has. These are the permissions the Auth0 Management API requires to be able to perform various operations, and which we can later choose from when we create the various roles for the users (in our case admin, user or editor).

I called my API Useradmin, and entered the various permissions I would need to update users and roles. Auth0 has a more detailed description of how this works.

Then I gave the machine-to-machine application Backend access to both the Auth0 Management API and the new Useradmin API that I just created:

However, this is not enough. You also have to click the small down arrow on the right hand side of each API, and give the Backend application the necessary permissions to the APIs. Jeg checked all the checkboxes with the permissions I created for the Useradmin API.

Then I had to configure the different user roles by selecting User Management from Auth0s main menu and then choose Roles. I created three roles: admin, editor and user. Then, for each role, I chose Add permissions and selected which API I wanted to add permissions from (in my case, the Useradmin API).

I gave the admin user all permissions defined in the Useradmin API. The roles user and editor don't need any permissions, as they should not be able to do anything "dangerous". I only check on the client if the user is a member of these roles to decide whether I should show buttons for editing content on the web site or not. Only users with an admin role will be allowed by my Gatsby Function to contact the Auth0 Management API (which also double-checks that the user that connects to it has the right permissions).

To avoid unnecessary API calls and simplify the code on the client side, I also wanted to make it possible to see what roles a user has when the user logs in. This is to be able to display roles on My Page, and for displaying buttons for user administration and content editing only when the user have the right roles. By default, the access token will only contain all the permissions the user has received (through its role). However, the name of the role will not be in the metadata of the access token. We have to fix that.

Auth0 has something called Flows and Actions that makes it possible to perform various operations when, for example, a user logs in. I selected the "flow" called Login, and then chose to add an "action" that runs right after the user logs in, but before the access token is sent.

When you create a new action, you will get an editor where you can enter your code. I entered the following code snippet, which adds all the roles of the user to the accesstoken before it is sent to the client:

/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https:/gartnerihagen-askim.no';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}

In Auth0s docs you can find a description of this, and more examples of what you can do with Auth0 Actions.

Fetch a list of all users

Finally, we can start creating the user admin dashboard for the web page. Let's start with the main page, the one that shows all registered users. In the next article, I will show how to make the components for editing users and deleting users.

I created a userAdminPage.tsx component that returns the user interface with a box at the top with information about who is logged in, a text field to filter / search for users, and a drop-down menu for selecting whether you want to display all users or only administrators or editors. Creating this was pretty straight forward , thanks to a great component library in Chakra UI.

I then created a custom hook (useGetAllUsers.js) that contacts the get-users-in-role API and passes along the access token of the logged in user. The custom hook returns the variables data, loading and error, as well as the getToken function that should be called if Auth0 needs the logged in user's permission for Auth0 to access the user account. This is something new users will see the first time they use the application.

If loading = true, I display my own custom <LoadingSpinner> component with loading message.

const { data, loading, error, getToken } = useGetAllUsers();

if (loading) {
  return (
    <LoadingSpinner spinnerMessage='Kobler til brukerkonto-administrasjon' />
  );
}

When the get-users-in-role API has finished fetching all the users, we find all the users in data.body.users. I use the array method .filter to filter out only the users I want to display, based on what I have entered in the search field. And then I sort all the names with .sort before I use .map to present each user in the array as a "user card" on the screen.

However, before we get to this point, some backend magic has happened in the Gatsby function get-users-in-role. First, we use the @serverless-jwt/jwt-verifier library to read the access token that the client sent when it made a GET request to get-users-in-role. This is the access token of the user who is logged in on the client, and is available in the request header. We use jwt.verifyAccessToken to check that the access token is valid. Then we verify the permissions included in the token, and that those permissions are the ones the user should have to be able to fetch user data from Auth0s Management API. The permissions the user must have to perform various operations are well described in the documentation for Auth0's Management API and in the documentation for the ManagementClient SDK I use to make everything a bit easier for myself.

Here is the first part of the code for the serverless function, the part of the code that checks permissions etc.:

// api/admin-users/get-users-in-role.ts

import { GatsbyFunctionRequest, GatsbyFunctionResponse } from 'gatsby';
const ManagementClient = require('auth0').ManagementClient;
const {
  JwtVerifier,
  JwtVerifierError,
  getTokenFromHeader,
} = require('@serverless-jwt/jwt-verifier');

const jwt = new JwtVerifier({
  issuer: `https://${process.env.GATSBY_AUTH0_DOMAIN}/`,
  audience: `https://${process.env.AUTH0_USERADMIN_AUDIENCE}`,
});

export default async function handler(
  req: GatsbyFunctionRequest,
  res: GatsbyFunctionResponse
) {
  let claims, permissions
  const token = getTokenFromHeader(req.headers.authorization);

  if (req.method !== `GET`) {
    return res.status(405).json({
      error: 'method not allowed',
      error_description: 'You should do a GET request to access this',
    });
  }

  // Verify access token
  try {
    claims = await jwt.verifyAccessToken(token);
    permissions = claims.permissions || [];
  } catch (err) {
    if (err instanceof JwtVerifierError) {
      return res.status(403).json({
        error: `Something went wrong. ${err.code}`,
        error_description: `${err.message}`,
      });
    }
  }

  // check if user should have access at all
  if (!claims || !claims.scope) {
    return res.status(403).json({
      error: 'access denied',
      error_description: 'You do not have access to this',
    });
  }

  // Check the permissions
  if (!permissions.includes('read:roles')) {
    return res.status(403).json({
      error: 'no read access',
      status_code: res.statusCode,
      error_description:
        'Du må ha admin-tilgang for å administrere brukere. Ta kontakt med styret.',
      body: {
        data: [],
      },
    });
  }
.
.
.

The way roles in Auth0 works, is that you first define the roles you want (in our case "user", "editor", "administrator"). Then you define what permissions each role should have. Finally, you assign one or more roles to the users.

Auth0 used to store roles in a separate app_metadata field in the access token for each user, but they now have a new solution for role-based authentication where we no longer get the role names included with the data for each individual user. This made fetching all users and the roles for each user much more cumbersome. I ended up building the following get-users-in-role API:

Use the Auth0 ManagementClient SDK to create a new ManagementClient that we call auth0.
Now that we have a ManagementClient called auth0, we can use auth0.getRoles() to fetch all available roles we have defined in Auth0. We then get an array with the roles user, admin and editor (we could of course hardcode this, but by using the getRoles method the solution is flexible and will still work if we later decide to create new roles with Auth0.
We use .map to create another array that contains all the users within each role. We do this with auth0.[getUsersInRole](https://auth0.github.io/node-auth0/module-management.ManagementClient.html#getUsersInRole) where we as a parameter uses the ID of each of the roles we retrieved with getRoles.
We now have a new array called userRoles that contains all three roles, with all users within each role. If a user has two roles (eg is both editor and admin), the user will excist several places.

[
        {
            "role": "admin",
            "users": [
                {
                    "user_id": "auth0|xxx",
                    "email": "kurt@lekanger.no",
                    "name": "Kurt Lekanger"
                }
            ]
        },
        {
            "role": "editor",
            "users": [
                {
                    "user_id": "auth0|xxx",
                    "email": "kurt@lekanger.no",                    
                    "name": "Kurt Lekanger"
                },
                {
                    "user_id": "auth0|yyy",
                    "email": "kurt@testesen.xx",                    
                    "name": "Kurt Testesen"
                },
                        ]
                }
... and so on!
]

This is not exactly what we need. We want an array with all users, where each user excists only once as an object containing an array with all the roles. Therefore, we need to build a new array - I have called it userListWithRoles. First I retrieve all users registered in the Auth0 database with const userList = await auth0.getUsers(). Then I use forEach with a nested for-loop inside to iterate over each user and check whether the user exists in the user list for this role. If a user has a role, that role is added to that user's roles array.

A diagram illustrating how it works and the ManagementClient SDK methods used:

Finally, I return userListWithRoles from the API and HTTP status code 200 to indicate that everything worked as expected. This is a shortened example of what is returned from the API. Note that each user now has a roles array:

  body: {
    users: [
      {
        name: 'Kurt Lekanger',
        email: "kurt@lekanger.no",
        user_id: 'auth0|xxxx',
        roles: ['admin', 'editor', 'user'],
      },
      {
        name: 'Kurt Testesen',
                email: "kurt@testesen.xx",
        user_id: 'auth0|yyyy',
        roles: ['editor', 'user'],
      },
    ],
  },

In reality, each user object in the userListWithRoles array also contains a lot of other metadata from Auth0, such as when the user last logged in, email address, whether the email has been verified, etc.

Here is the rest of the source code for the get-users-in-role API:

// // api/admin-users/get-users-in-role.ts 
.
.
.
  const auth0 = new ManagementClient({
    domain: `${process.env.GATSBY_AUTH0_DOMAIN}`,
    clientId: `${process.env.AUTH0_BACKEND_CLIENT_ID}`,
    clientSecret: `${process.env.AUTH0_BACKEND_CLIENT_SECRET}`,
    scope: 'read:users read:roles read:role_members',
  });

  try {
    const roles: string[] | undefined = await auth0.getRoles();
    const allUsersInRoles = await roles.map(async (role: any) => {
      const usersInRole = await auth0.getUsersInRole({ id: role.id });
      return { role: role.name, users: usersInRole };
    });

    const userRoles = await Promise.all(allUsersInRoles); // Get a list of all the roles and the users within each of them,
    const userList = await auth0.getUsers(); // and a list of every registered user

    let userListWithRoles = [];
    userList.forEach((user) => {
      for (let i = 0; i < userRoles.length; i++) {
        if (
          userRoles[i].users.find((element) => element.user_id === user.user_id)
        ) {
          const existingUserToModify = userListWithRoles.find(
            (element) => element.user_id === user.user_id
          );
          if (existingUserToModify) {
            existingUserToModify.roles = [
              ...existingUserToModify.roles,
              userRoles[i].role, 
            ];
          } else {
            userListWithRoles.push({
              ...user,
              roles: [userRoles[i].role],
            });
          }
        }
      }
    });

    res.status(200).json({
      body: {
        users: userListWithRoles,
      },
    });
  } catch (error) {
    res.status(error.statusCode || 500).json({
      body: {
        error: error.name,
        status_code: error.statusCode || 500,
        error_description: error.message,
      },
    });
  }
}

Next step: Useradmin with Gatsby Functions. Update, create and delete users

Feel free to take a look at the finished website here: https://gartnerihagen-askim.no

The project is open source, you can find the source code at my Github.

Here's a video showing the live site with the login protected pages and the user admin dashboard:

This is a translation, the original article in Norwegian is here: Slik lagde jeg et brukeradmin-panel med Gatsby Functions og Auth0

Part 4: Setting up continous deployment on Netlify

Kurt Lekanger — Sun, 12 Sep 2021 13:35:15 +0000

I have built new web pages for my condominium using Gatsby, but they need a server to run on as well - and I need the static pages to be automatically rebuilt when new content is added. This is how I set everything up.

The most obvious choice for hosting the new web site was for me Netlify. I knew Netlify well from previous projects and also have used it for my personal website lekanger.no. The most important reason, however, was how easy it is to deploy a Gatsby website to Netlify. Another reason why i chose Netlify is that it is free as long as you have relatively modest traffic. We are a small condominium where everyone pays around 70 euros a month in common expenses, and if we want to keep the expenses low for our residents, we should avoid high operating costs for the web site.

Gatsby Cloud or Netlify?

Lately, Gatsby has increasingly been pushing hard on its own hosting solution, Gatsby Cloud. Every time Gatsby launches something new, they focus almost exclusively on Gatsby Cloud. Support for new functionality is often available first on Gatsby Cloud.

There is no doubt that Gatsby works hard to make the developer experience on Gatsby Cloud superior to everything else. You often have to use special plugins or make an extra effort to find out how to do things with Netlify. With Gatsby Cloud it just works. For example, Gatsby recently launched built-in support for serverless functions, which makes it easy to build backend APIs for your website. When this was launched, it was difficult to find information anywhere about how you could get Gatsby Functions working on something else than Gatsby Cloud. However, this is possible - and Netlify has posted a user guide here describing how you set it up by installing a separate plugin. Now Netlify has even added auto-install for this plugin, so you don't have to do anything to get Gatsby Functions working on Netlify. I should mention that Netlify have had support for serverless functions for a long time (Netlify Functions, but with built-in support in Gatsby, everything has become a little more streamlined for those of us building Gatsby sites.

I think it's important to have a performant web site. Like Netlify, Gatsby Cloud now also has its own CDN solution operated by Fastly, which means that the websites are delivered to users in a flash almost no matter where in the world they may be.

For now, I'm running Netlify, but you should be aware of the options when you're making your choice. If I were to start the project again today, perhaps Gatsby Cloud would be the most obvious choice for me.

Setting up continous deployment

There are two ways to deploy a website to Netlify: 1) Let Netlify know where the git repo of the website is located, or 2) Run gatsby build locally to create a production build of the website and then drag-and-drop the public folder from your project over to Netlify (see below).
If you want continous deployment you should choose to create a new site from git (1).

I wanted continuous deployment, so I chose to give Netlify access to the git repo on Github by pressing the large, green "New site from Git" button (there is also support for Gitlab and Bitbucket). With continuous deployment, Netlify will "listen" to changes in the git repo and automatically rebuild the page if anything has changed.

By default, Netlify will use the master (main) branch, but you can also use another branch. This can be useful if you want to create a "staging" area for testing. Then you can have a git branch called, for example, staging or development, and have Netlify building those as separate websites that you can use to test things out before you deploy to production. Creating staging sites and the like can be automated through what Netlify calls deploy contexts. This is not something I have set up yet for the condominium's website - but take a look at the documentation if you want to learn more about it.

You probably do not need to change the default settings, but if you want you can define which command to run to build the page (default is npm run build).
I kept the default settings.

When this is done, you have to set up all the environment variables you're using in your code. That is, all of the API keys and various secrets that you normally keep in an .env file (which you MUST remember to put in your .gitignore file , so that unauthorized persons do not get hold of it).

For the condominium's websites, there were environmental variables for two services/APIs I had to define:

Contentful: 1) A space id to the site I had created on Contentful with all the content. 2) An access token for Gatsby to be able to authenticate itself to Contentful and be able to download the content. You can find these by logging in to your site on Contentful, going to the Settings menu and then selecting API Keys.
Auth0: Here I needed two things: 1) Auth0 domain, 2) Client ID.

Those were the variables I had to set up when I started the project, but later on I have also added a user admin dashboard and other things, so my list of environment variables has gotten quite long:

You have to set up all the environment variables. Just copy paste them from your local development .env-file into Netlify's dashboard.

You cand find all of them in an example file in the Github repo for this project.

As soon as I pointed Netlify to the correct git repo and copied over the environment variables from my local .env file, the website was built automatically by Netlify. The web pages are cached on Netlify's CDNs, so they are blazingly fast no matter where you are in the world.

By default, you get a slightly cryptic URL - but I made sure quite quickly to register a proper domain for the condominium.

You can read more about deploying to Netlify here.

Trigger builds when new content is published

Since the new Gatsby site for our condominium is a static website based on content fetched from a "headless CMS" (Contentful) when the pages are built, I needed a way to automatically rebuild the site when someone published new content.

This is quite easy to solve:

Go to Site settings in Netlify and select Build & deploy
Scroll down to Build hooks and press Add build hook
Give the hook a name (I called it "Trigger build") and choose which branch of the git repo you want to build.
In Contentful, go to Settings and Webhooks. Select Add webhook and use the URL of the hook you created on Netlify. You should do a POST request to this hook, and select that it should trigger only when new content is published.

With build hooks you can trigger new builds when new content is added.

When you add new content, the web site has to be rebuilt before the content shows up on the live site. This can take a few minutes, but has gotten a lot quicker lately thanks to a lot of improvements in Gatsby.

If you want previews of unpublished content, you have to use Contentfuls preview API to fetch unpublished content. You could build a preview page in Gatsby for this. However, I haven't done this yet for our web site - I just edit the content in Contentful and wait for the deploy to finish.

Next step: Making a user admin dashboard with Gatsby Functions and Auth0

Feel free to take a look at the finished website here: https://gartnerihagen-askim.no

The project is open source, you can find the source code at my Github.

This is a translation, the original article in Norwegian is here: Del 4: Slik bygget jeg sameiets nye nettsider. Kontinuerlig utrulling til Netlify

Part 3: Authentication and private routes in Gatsby

Kurt Lekanger — Sun, 12 Sep 2021 13:35:06 +0000

In part 1 and 2 of this series I described the technology choices I made before starting to build new web pages for my local condominium. I also went through how I configured Gatsby on the frontend and Contentful on the backend.

Gatsby is often referred to as a "static site generator", which means that when you enter the command gatsby build, Gatsby starts retrieving content from a CMS, an API or perhaps markdown files on the disk. Content and data from different sources are combined, and Gatsby renders static HTML files and packs everything together - without you having to know anything about Webpack configuration, code splitting or other things that can often be a bit complicated to set up.

Great performance is one of the many benefits of static web sites. Static sites are also secure. Because the web pages are created as you build the page, and the user is served static HTML pages, the attack surface is significantly reduced. For example, it is not possible for an attacker to access content from databases or your CMS, other than the content Gatsby already has retrieved when the static pages were generated.

Gatsby does not have to be just static pages

As mentioned in the first parts of this series, I wanted to have a separate area on the website that would only be available to our residents (behind a login page). These pages should not be static, but fetch content dynamically as needed, in my case depending on whether the user is logged in or not.

Before I go into how I made the login functionality, I want to talk about how Gatsby can handle pages that are only available to logged in users.

Gatsby supports so-called client-only routes. This makes it possible to create pages that exist only on the client (in the browser) and where static HTML pages are not created in the /public folder when you run the gatsby build command. Client-only routes work more like a traditional single page app in React, and by using Reach Router which is built into Gatsby, you can handle the various routes that only logged-in users should see.

For the user login, we need an authentication solution. I didn't want to build this myself, so I chose Auth0. This is a well recognized and proven solution with a lot of features I will need when building a dashboard for user administration. Using Auth0, I can protect access to all client-only routers.

Below is a simplified diagram that shows how this works on my web site. The blue boxes are static pages created when building the Gatsby site. For the route /information, a static page is also created which, if the user is not logged in, shows a message informing you that you must log in to see the content. If the user is logged in, Reach Router is used to display the correct React component depending on which route the user is trying to reach. This is wrapped in a <Privateroute> component that uses a higher order component in auth0-react called withAutenthicationRequired to check if the user is logged in or not.

A PrivateRoute component works as a "gate keeper", letting through logged in users only.

To simplify the process of making client-only routes, I use an official Gatsby plugin called gatsby-plugin-create-client-paths. When you have installed this plugin, you can edit gatsby-config.js to configure which routes you want to be private (Gatsby will not create static pages out of these):

// ./gatsby-config.js

plugins: [
{
      resolve: `gatsby-plugin-create-client-paths`,
      options: { prefixes: [`/informasjon/*`, `/min-side/*`] },
},
]

In the code example above, every path (url) ending in /informasjon and /min-side ("My page" in Norwegian) will not be static pages, but render the routes I have set up in src/pages/informasjon.tsx or src/pages/min-side.tsx. On the condominium's website, there is a menu item on the navigation bar called For residents that navigates to https://gartnerihagen-askim.no/informasjon. To create this client-only route in Gatsby, I created the file src/pages/informasjon.tsx and used Reach Router to display different React components depending on the route. For example, if the user visits the web page on the route /informasjon/dokumenter, the <Dokumenter> component should be displayed.

This is my informasjon.tsx page, and how the routing is set up (abbreviated, see complete source code at https://github.com/klekanger/gartnerihagen):

// ./src/pages/informasjon.tsx

import * as React from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { Router } from '@reach/router';
import PrivateRoute from '../utils/privateRoute';

import InfoPage from '../components/private-components/informasjon';
import Referater from '../components/private-components/referater';

import LoadingSpinner from '../components/loading-spinner';
import NotLoggedIn from '../components/private-components/notLoggedIn';

const Informasjon = () => {
  const { isLoading, isAuthenticated, error } = useAuth0();

  if (isLoading) {
    return (
      <Box>
        <LoadingSpinner spinnerMessage='Autentiserer bruker' />
      </Box>
    );
  }

  if (error) {
    return <div>Det har oppstått en feil... {error.message}</div>;
  }

  if (!isAuthenticated) {
    return <NotLoggedIn />;
  }

  return (
    <Router>
      <PrivateRoute path='/informasjon' component={InfoPage} />
      <PrivateRoute
        path='/informasjon/referater/'
        component={Referater}
        title='Referater fra årsmøter'
        excerpt='På denne siden finner du referater fra alle tidligere årsmøter. Er det noe du savner, ta kontakt med styret.'
      />
    </Router>
  );
};

export default Informasjon;

My <PrivateRoute> component looks like the code snippet below. This component ensures that the user must be logged in to get access. If not, the user will get Auth0's authentication popup:

// ./src/utils/privateRoute.tsx

import * as React from 'react';
import { withAuthenticationRequired } from '@auth0/auth0-react';

interface IPrivateroute {
  component: any;
  location?: string;
  path: string;
  postData?: any;
  title?: string;
  excerpt?: string;
}

function PrivateRoute({ component: Component, ...rest }: IPrivateroute) {
  return <Component {...rest} />;
}

export default withAuthenticationRequired(PrivateRoute);

Navbar with login

As mentioned, we need an authentication solution to find out who should have access and who should not. The first version of the condominium's website was set up with Netlify Identity and Netlify Identity Widget, a solution that was very easy to configure.

However, it soon became apparent that Netlify Identity had some limitations. One was that the login alert was not in Norwegian (I translated it and opened a pull request, but could not wait for it to go through. It's been 7 months now...). The other reason for not sticking with Netlify Identify was that I started working on a dashboard for user account management where I would need some more advanced functionality than Netlify Identity Widget could provide. After some research, I ended up choosing Auth0.

After registering and setting up everything at Auth0.com, I installed the Auth0 React SDK with: npm install @auth0/auth0-react

Auth0 React SDK uses React Context, so you can wrap your entire application in an Auth0Provider so that Auth0 knows whether the user is logged in or not, no matter where in the application the user is. When your application is wrapped in Auth0Provider, you can in any component import the useAuth hook like this: import { useAuth0 } from '@auth0/auth0-react' and from useAuth retrieve various methods or properties that have to do with login, for example check if the user is authenticated, bring up a login box, etc. Example: const { isAuthenticated } = useAuth0() makes it easy to later check if the user is logged in by doing this: if (!isAuthenticated) { return <NotLoggedIn /> }

So how do we wrap our application in Auth0Provider? It's quite straightforward: In Gatsby you can wrap the root element of the web page with another component by exporting wrapRootElement from the gatsby-browser.js file. Read more about it in the Gatsby documentation.

This is what my gatsby-browser.js file looks like, with Auth0Provider set up so that all pages on the webpage have access to information about whether the user is logged in or not:

// ./gatsby-browser.js

import * as React from 'react';
import { wrapPageElement as wrap } from './src/chakra-wrapper';
import { Auth0Provider } from '@auth0/auth0-react';
import { navigate } from 'gatsby';

const onRedirectCallback = (appState) => {
  // Use Gatsby's navigate method to replace the url
  navigate(appState?.returnTo || '/', { replace: true });
};

export const wrapRootElement = ({ element }) => (
  <Auth0Provider
    domain={process.env.GATSBY_AUTH0_DOMAIN}
    clientId={process.env.GATSBY_AUTH0_CLIENT_ID}
    redirectUri={window.location.origin}
    onRedirectCallback={onRedirectCallback}
  >
    {element}
  </Auth0Provider>
);

export const wrapPageElement = wrap;

I created a login button in the navigation bar at the top of the web page. When the user tries to log in, he or she is sent to Auth0's login page - and redirected to the condominium's website if the username and password are correct.

The login button also gives access to a My page ("Min Side") where the user can see information about who is logged in, and has the opportunity to change passwords. For security reasons, the password is not changed directly, but instead the Change Password button will send a POST request to Auth0's authentication API with a request to change the password. Auth0 has a description of how this works here.

The user has access to "My Page" under the login button when logged in.

Securing the content

In the original project I used Gatsby's GraphQL data layer to fetch content for the protected routes, using Gatsby's useStaticQuery hook. That meant that all the content was fetched during build time - even the content that should be accessible to logged in users only. The users could not access these protected routes without being authenticated, but technical users could find private content via the network tab in the browsers dev tools.

To prevent this, I had to rewrite the components used in client-only routes to use Apollo Client in stead of Gatsbys GraphQL data layer for fetching data. Data that should be available on the client only at run-time are fetched from the Contentful GraphQL Content API (and not via the build-time gatsby-source-contentful plugin) using Apollo Client.

To get this to work I had to make changes in both how rich text was handled (since it was different depending on whether I used gatsby-source-contentful or retrieved the content dynamically from Contentfuls GraphQL content API). I also had to build a custom component for handling images delivered from the Contentfuls Image API, since I could not use Gatsby Image with Contentful's own API. I wanted the same performance as with Gatsby Image, and the images delivered in "correct" sizes depending on screen width. I won't get into all the details, but you can find the complete source code at my Github here, and my custom image component here.

In the next part of this series, I will go through how I deployed the final web site to Netlify, using continous deployment.

In the two final parts of the series, I will show how I built the user admin dashboard that let's administrators create or update the users that should have access to the protected routes of our web page.

Next step: Setting up continous deployment to Netlify

Feel free to take a look at the finished website here: https://gartnerihagen-askim.no

The project is open source, you can find the source code at my Github.

This is a translation, the original article in Norwegian is here: Del 3: Slik bygget jeg sameiets nye nettsider. Autentisering og private ruter i Gatsby

Part 2: A new web page for our condo. Setting up Gatsby and Contentful.

Kurt Lekanger — Sun, 12 Sep 2021 13:34:54 +0000

In part 1 of this mini-series I wrote about the technology choices I made when I started building new web pages for my local condominium. If you haven´t done it already, read about why I chose React/Gatsby and Chakra UI on the frontend, Contentful as a headless CMS and Netlify for hosting everything. I also needed an authentication solution for those parts of the web site that should only be accessible for logged in residents only.

Building the foundation

Starting a Gatsby project is as simple as typing npm init gatsby on the command line and answering a few simple questions (or gatsby new if you have Gatsby-CLI installed). Gatsby will then set up a starter project for you, which you can then modify.

You will be asked which CMS you want to use for storing the content, and can choose between Wordpress, Contentful, Sanity, DatoCMS, Shopify or Netlify CMS. You can use almost anything else with Gatsby as well - but Gatsby can set up a number of things for you automatically if you choose one of the predefined options. You will also be asked if you want to have a specific styling system pre-installed, such as Sass, Styled components, Emiton, PostCSS or Theme UI.

Gatsby can prepare a number of things for you in advance.

However, I chose to start from scratch, and installed the various dependencies I needed as I went along with the project. I needed gatsby-source-contentful to get content from my Contentful headless CMS. And I wanted to make life a little easier for myself by creating the user interface with Chakra UI. I also needed some other packages, like dotenv to handle environmental variables (such as access tokens for Contentful, and other things I didn't want to include in the source code on Github).

When everything is set up, you will get a page that looks something like this when entering gatsby develop on the command line and visiting http://localhost:8000:

The Gatsby documentation is awesome, and the start page created by the gatsby new command links to a lot of useful information.

The first thing you should do, is of course to remove this dummy page.

In Gatsby, routing is as simple as creating a React component in the /src/pages folder and exporting it. For example, if you export a component from the /src/pages/test.js file, you will have a route on /test (ie you can type localhost:8000/test in the browser to reach it). The main page - ie the front page of the website - is /src/pages/index.js. This is how my index.js file looks like on my finished website:

// ./src/pages/index.js

import * as React from 'react';
import SEO from '../components/seo';
import CookieConsent from '../components/cookieConsent';
import HeroWide from '../components/sections/hero-wide';
import ArticleGrid from '../components/sections/articleGrid';

const IndexPage = () => {
  return (
    <>
      <SEO />
      <CookieConsent />
      <HeroWide />
      <ArticleGrid />
    </>
  );
};

export default IndexPage;

Normally I would include a Layout component here, for consistent layout with header, footer, etc. across all pages. But since I use Chakra UI, I have put the Layout component elsewhere where the Layout component is wrapped by <ChakraProvider> which is necessary for it all to work. This also enables theme based styling using Chakra UI. I created the file ./src/chakra-wrapper.js:

// ./src/chakra-wrapper.js

import * as React from 'react';
import { ChakraProvider } from '@chakra-ui/react';
import Layout from './components/layouts/layout';
import theme from './theme/';

export const wrapPageElement = ({ element }) => {
  return (
    <ChakraProvider resetCSS theme={theme}>
      <Layout>{element}</Layout>
    </ChakraProvider>
  );
};

And then, in ./gatsby-browser.js and ./gatsby-ssr.js:

import * as React from 'react';
import { wrapPageElement as wrap } from './src/chakra-wrapper';
.
.
.
export const wrapPageElement = wrap;

This means that the entire page is wrapped in ChakraProvider, and then the Layout component which wraps everything else and includes a header and a footer. In the <ChakraProvider> component in the top code snippet, I also pass in the theme I have defined for the page as a prop.

I ended up with the folder structure below, where I have put all reusable React components in /src/components, pages under /src/pages, page templates under /src/templates and Chakra UI themes under /src/theme:

src
├── components
│   ├── article.tsx
│   ├── layouts
│   │   └── layout.tsx
│   ├── private-components
│   └── sections
│       ├── articleGrid.tsx
│       ├── footer.tsx
│       ├── header.tsx
│       └── hero-wide.tsx
├── pages
│   ├── 404.tsx
│   ├── index.tsx
│   ├── informasjon.tsx
│   └── min-side.tsx
├── templates
│   ├── blog-archive-template.tsx
│   ├── blog-template.tsx
│   └── page-template.tsx
├── theme
│   ├── colors.js
│   ├── components
│   │   ├── button.js
│   │   ├── heading.js
│   │   └── text.js
│   ├── index.js
│   ├── renderRichTextOptions.js
│   ├── styles.js
│   └── textStyles.js
└── utils
    └── privateRoute.tsx

As you can see, I chose to rename the .js files for the React components to .tsx, in order to use TypeScript in my components - and to reduce the risk of bugs when I pass data as props between components.

Fetch content from Contentful

As mentioned, I wanted to use Contentful for my content. Contentful is a headless CMS system, which means that the content is decoupled or separated from the front end. This makes it relatively easy if I later on wants to switch to another frontend or backend, or fetch content from the same source to another web page or maybe a mobile app. When using Gatsby, you can fetch content from virtually any source by making GraphQL queries in your code. There are a lot of ready-made plugins that make this very easy, whether you want to fetch data from markdown files, a headless CMS like Contentful or Sanity, or from an online shopping solution like Shopify. I used Gatsby's official Contentful plugin, gatsby-source-contentful.

When you have installed and configured the plugin, you can visit localhost:8000/__graphiql to create the GraphQL queries. In the left column of the GraphiQL interface you get a view of all available data (including content from Contentful). The middle column is for creating the queries - and the column on the right shows the result of a query after you press the Run button. GraphiQL makes it very easy and straightforward to test different queries and check that you get back the data you expect, before copying the query into your code.

GraphiQL is a user-friendly interface for creating GraphQL queries.

But before I could see my data in GraphiQL, I had to set up everything in Contentful. I first had to define a Content model, which is a description of the different types of content - and what fields should be available for each content type. For example, I have a content type called Blog Post, which contains fields such as Title, Summary, Top Image, Body Text and Author. For each of the fields you must define the type of the content - such as text, numbers, boolean values, media (images, video, etc). You can also create references between different types of content, for example links between a blog post and one or more authors (where Author is a content type as well).

I defined separate content types for front page text and pages (for example information pages and contact pages). In addition, I created a content type called Service menu, which is used to change a menu with information for the residents of the condominium - including links for downloading meeting minutes, a list of all the residents and other useful information. All content in the Service menu will require login.

Contentful: Start by making a content model with all the different types of content you want. Then define which fields each content type should include.

Field definitions in Contentful.

Generation of static web pages

One of the things that makes websites created in Gatsby extremely fast is that Gatsby generates static web pages. This means that when you run gatsby build, Gatsby will retrieve content from Contentful (or other sources) and build every HTML page for you. Thus, 100/100 in Lighthouse should be within reach:

100 of 100 in Lighthouse. You can do it!

As I have mentioned, all components exported from the /src/pages folder will automatically be converted to static HTML pages. But to be able to programmatically create my own pages for each blog post and other content, I used one of Gatsby's built-in APIs, createPages. To explain:

When you build a Gatsby page, code in the gatsby-node.js file will run once before the page is built. The createPages (plural) API allows you to run a GraphQL query to retrieve content (such as blog posts) - in our case from Contentful. Then you can run a so-called action called createPage (singular) on each blog post. createPage receives as a parameter the React component you want to use as a page template, along with context data that the page template will receive as props. Context data in my case is the ID of the article in Contentful. Inside the page template you run a new GraphQL query where you only retrieve the blog post that has the correct ID, and then you retrieve everything you need to display the content - such as title, introduction, body text, images, etc. The page template is like any normal React component.

My gatsby-node.js looks like this (abbreviated - there are also several GraphQL queries and actions to create other types of pages. See my Github for full source code):

// ./gatsby-node.js

const path = require(`path`);

exports.createPages = ({ graphql, actions }) => {
  const { createPage } = actions;
  const blogPostTemplate = path.resolve(`src/templates/blog-template.tsx`);

.
.
.
  return graphql(`
    {
      publicPosts: allContentfulBlogPost(
        filter: { privatePost: { eq: false } }
      ) {
        nodes {
          contentful_id
          slug
        }
      }
    }
  `).then((result) => {
    if (result.errors) {
      throw result.errors;
    }

  const blogNodes = (result.data.publicPosts || {}).nodes || [];

  // Create public blog post pages.
  // Skip private pages (in graphQl query)
  blogNodes.forEach((node) => {
    const id = node.contentful_id;
    const slug = node.slug;
    createPage({
      // Path for this page — required
      path: `/blog/${slug}`,
      component: blogPostTemplate,
      context: { id },
    });
  });

.
.
.
}

In the file blog-template.tsx I fetch the blogposts one-by-one from Contentful using the GraphQL query below. Note the variable $id in the GraphQL query. This ID comes from the context parameter sent from createPage in gatsby-node.js and gives us the content for the correct blog post, and nothing morge.

// ./src/templates/blog-template.tsx

export const query = graphql`
  query BlogPostQuery($id: String!) {
    contentfulBlogPost(contentful_id: { eq: $id }) {
      title
      createdAt(formatString: "DD.MM.YYYY")
      updatedAt(formatString: "DD.MM.YYYY")
      author {
        firstName
        lastName
      }
      excerpt {
        excerpt
      }
      bodyText {
        raw
        references {
          ... on ContentfulAsset {
            contentful_id
            __typename
            title
            description
            gatsbyImageData(layout: CONSTRAINED, aspectRatio: 1.6)
          }
        }
      }

      featuredImage {
        gatsbyImageData(layout: CONSTRAINED, aspectRatio: 1.6)
        file {
          url
        }
        title
        description
      }
    }
  }
`;

Then I destructure the data I want from the query and use the data in the page template component:

// ./src/templates/blog-template.tsx
.
.
.
const {
    title,
    author,
    createdAt,
    updatedAt,
    bodyText,
    excerpt,
    featuredImage,
  } = contentfulBlogPost;

  return (
    <>
      <SEO
        title={title}
        image={featuredImage?.file?.url || null}
        description={excerpt?.excerpt || null}
      />
      <Article
        title={title}
        bodyText={bodyText}
        createdAt={createdAt}
        updatedAt={updatedAt}
        mainImage={featuredImage}
        author={author}
        buttonLink='/blog'
      />
    </>
  );
}
.
.
.

Since I often need to present content in article format, with a featured image, title, introduction, author, etc., I created an <Article> component for this, and pass data to it via props.

One challenge I encountered was how to render content that was defined as Rich Text in Contentful. Content in Rich Text fields are based on blocks, and when you do a GraphQL query, you're getting back JSON containing nodes with all the content in. There are a lot of different ways to render this content, and Contentful has a little more info here. I used import {renderRichText} from 'gatsby-source-contentful/rich-text' and then I could use {renderRichText (bodyText, renderRichTextOptions)} in my Article component to render the contents of bodyText. renderRichTextOptions is a component I import at the beginning of the <Article> component, and inside renderRichTextOptions I can then define how for example a <H1> title or image should be rendered (<Text> and <Heading> in the code below are Chakra UI components):

// ./src/theme/renderTichTextOptions.js
.
.
.
const renderRichTextOptions = {
  renderMark: {
    [MARKS.BOLD]: (text) => <strong>{text}</strong>,
    [MARKS.UNDERLINE]: (text) => <u>{text}</u>,
    [MARKS.ITALIC]: (text) => <em>{text}</em>,
  },
  renderNode: {
    [BLOCKS.PARAGRAPH]: (node, children) => (
      <Text
        textAlign='left'
        my={4}
        fontSize={{ base: 'sm', sm: 'md', md: 'lg' }}
      >
        {children}
      </Text>
    ),
    [BLOCKS.HEADING_1]: (node, children) => (
      <Heading as='h1' textAlign='left' size='4xl'>
        {children}
      </Heading>
    ),
.
.
.

It's also possible to use another library, rich-text-react-renderer, but the way I did it worked very well and gave me the flexibility I needed.

Styling

Chakra UI have components for everything you need to create beautiful web pages, using components like <Badge>, <Alert>, <Text>, <Heading>, <Menu>, <Image>, and so on.

As Chakra UI is a theme based component library, you dont't have to write a single line of CSS. Instead, you just customize the standard theme if you want a different look-and-feel.

With Chakra UI you get responsive design right out of the box, with pre-defined breakpoints (which you can change if you want). You do not need to manually create media queries, but can do as I have done in the example below in your JSX code ( is a Chakra UI component intended for titles and renders by default an <H2>- tag, but in the example I have chosen to render it as <H1>):

<Heading
   as='h1'
   fontSize={['4xl', '6xl', '6xl', '7xl']}
   textAlign={['center', 'left', 'left', 'left']}
   pb={4}
>

Here we define font size and text alignment for four different screen sizes. That's actually all you need to do to get perfect responsive design with Chakra UI.

Or you could do like this to use Chakra UI's CSS Grid component and define that you want 1 column on small and medium screen sizes, and 2 columns on larger screens:

<Grid
    templateColumns={{
      sm: 'repeat(1, 1fr)',
      md: 'repeat(1, 1fr)',
      lg: 'repeat(2, 1fr)',
      xl: 'repeat(2, 1fr)',
    }}
    pt={16}
    gap={16}
    mb={16}
    mt={0}
    maxWidth='95vw'
    minHeight='45vh'
  >

With Chakra UI you also get a web site with excellent accessibility, without you needing to think about aria-tags or other things.

Have a look at https://chakra-ui.com for more info and more examples.

Next step: Authentication and protected routes

Feel free to take a look at the finished website here: https://gartnerihagen-askim.no

The project is open source, you can find the source code at my Github.

This is a translation, the original article in Norwegian is here: Del 2: Slik bygget jeg sameiets nye nettsider. Grunnmuren er på plass

Part 1: How I built our condos's new web pages with Gatsby and Chakra UI

Kurt Lekanger — Sun, 12 Sep 2021 13:34:41 +0000

We have thousands of small and large condominium associations and housing cooperatives in Norway where I live, and common to them all is that they often need a place to publish information to their residents. But many small condos do not have large budgets to develop their own websites.

I'm a board member in a small condominium with 21 sections, and until recently we have managed with nothing more than email and a Facebook page to get information out to the residents. The plan was to continue like that - until a newly moved-in neighbor came over and asked why we did not have a website where he could find useful info. And why not? I just had to figure out how we could build it without spending too much money.

The cheapest solution was of course to build everything myself.

I am a self-taught developer who have been coding in JavaScript and React for a few years, mostly on a hobby basis. Just before Christmas 2020 I came across a new component library called Chakra UI which promised making it easy to create great looking user interfaces without having to build everything from scratch.

After playing a bit with Chakra UI a few weekends and late nights, I decided to make something useful - instead of just another test website (or to-do app, God forbid). Maybe it was possible to create and operate a new website for the condo completely free of charge? I had to give it a try.

The result was a quite performant website that does not cost the condominium a penny to run - except for the 120 kroner (~12 euro) a year for the domain https://gartnerihagen-askim.no.

This is how the front page of the finished web site looks like:

Separate area for logged-in users

The purpose of the web site was first and foremost to give the residents a place to find useful information for residents only. But the web site should also promote the condo and the neighbourhood for potential home buyers.

I like to have a plan before I begin, so I started drawing a few sketches and wireframes with my favorite tool for these things: Figma.

The front page should be accessible to everyone, but it was also necessary to keep some content behind a login:

This is how the pages for logged in users look like:

Technology choices

I wanted the new web site to be as user friendly as possible, while also being lightning fast and using best practices in modern web development. I wanted to use functional and reusable components in React.js with "hooks" that lets me handle state easily.

I also decided to use TypeScript to reduce the risk of bugs when passing props down to variuous components - but also because using TypeScript gives me incredibly useful information in VS Code during coding:

Languages and frameworks - frontend

I decided quite early in the project to build the web site using the React framework Gatsby. I also considered using Next.js, but I had much more experience with Gatsby and then it also became the natural choice for me.

One of the benefits of Gatsby is that you get websites that are extremely fast. Gatsby creates static HTML pages that are very well optimized, including best-in-class optimization of images (which has become even better with Gatsby 3.0). It is also easy to create web pages with great SEO (search engine optimization).

To speed up the process of making a nice user interface, I chose Chakra UI. With Chakra UI, you also get a number of bonus benefits, such as compliance with WAI-ARIA standards for accessibility, and that you can customize your own themes for your website. This means that you hardly need to write any CSS at all, but can define color palettes, fonts, distances and more by expanding the default theme (which already looks very nice).

Chakra UI also makes it easy to create responsive websites, in fact without having to write a single media query.

Backend

When it came to where I should host the site, the choice stood between Gatsby's own Gatsby Cloud , or Netlify. I decided on the latter, as little traffic and the modest needs of the condominium would make it possible to run the website on the free tier.

Getting a Gatsby website up and running on Netlify is as simple as pointing Netlify to the code repository in Git. As soon as I push new code to the project's main branch on Github, Netlify automatically runs a new build of the site.

For publishing content, I wanted a headless CMS solution. I considered both the Norwegian headless CMS solution Sanity and headless Wordpress, as I had experience with both. For example, my personal website lekanger.no uses Sanity, while Wordpress has also come a long way as a "headless" CMS.

However, the choice fell on Contentful. The most important prerequisites were that the CMS I chose should be easy to use, and that it could deliver the content to Gatsby via GraphQL. Contentful has an official plugin for Gatsby that makes it easy to source the content into Gatsby. And although Contentful is relatively expensive, you should have quite a lot of content and traffic before you have to upgrade from the free tier.

Authentication

Some areas on the condominium's website should be accessible to logged in users only. For that I used Gatsby's "Client-only routes". Unlike regular Gatsby pages, pages on client-only routes are not static, pre-generated pages. Instead they work more like a traditional React app running on the client. More about this in my next article, where I go through how the website are built.

In the first version of the website, I used Netlify Identity, which is Netlify's own authentication solution. With Netlify Identity Widget it is easy to add authentication, but I quickly discovered that I missed some more advanced functionality. I therefore switched to Auth0, which to a greater extent allowed me to tailor the login solution. Auth0 also had some functionality I needed to create a user admin dashboard, like role-based authentication.

Time to start coding!

In the next article, I will go into more details about how the website are built, how I built the pages that should require login, as well as some of the challenges I encountered along the way.

Next step: Part 2: A new web page for our condo. Setting up Gatsby and Contentful.

Feel free to take a look at the finished website here: https://gartnerihagen-askim.no

The project is open source, you can find the source code at my Github.

Here's a video showing the live site with the login protected pages and the user admin dashboard:

This is a translation, the original article in Norwegian is here: Slik bygget jeg nye nettsider til sameiet med Gatsby og Chakra UI