Forem: Julian Bustos

How to Integrate Google APIs in Your Next.js Project

Julian Bustos — Tue, 15 Jul 2025 00:48:49 +0000

Ever thought about using Google Docs or Sheets as more than just documents or spreadsheets? Imagine them as dynamic content sources or even simple databases for your applications. In this guide, we'll dive into how to set up Google's APIs to unlock these powerful services within your projects, transforming how you manage and access data.

The specific version of Next.js you're using won't impact this guide, as our focus is solely on obtaining API keys from Google's platform.

We will first need to create a new Service Account to do so go here

Click on Start Free

Read the terms of service and click Agree & Continue.

Create your Payment Profile (you won't be charged).
Select Individual Profile Type if you're not a business.
Click Create.
Now add a payment method.
Click Start Free.
Select your Cloud Platform options.

Great! Now that we have a Service Account set up, look for the menu on the left and click on APIs & Services.

Enable APIs & Services

Search for Google Sheets API and select it

Click Enable

Great now we have the google sheets API enabled now let's create the credentials so we can programmatically connect to it.

Click on Create Credentials

Select Application Data & click Done

Now click on the IAM & Admin in the left menu and then click Service Accounts

Now click on Create Service Account

Give your account a name and a description and click Create And Continue

Select Owner as the Role and click Continue

We can click Done on the final step.

Now we can manage the keys for this account which will allow us to connect to Google Sheets.

Click on the 3 dots and select Manage Keys

Click on Add Key and then on Create new key

Select the JSON option and click Create

Save it somewhere safe and then open it in your code editor

Great all we really care about are the private_key and the client_email, these will allow us to establish the connection.

Go back to your Nextjs Project and in the .env.local (if you don't have a .env file yet create one in the root of your project) file let's create the environment variables we will need.

# .env.local

GOOGLE_SERVICE_ACCOUNT_EMAIL=
GOOGLE_PRIVATE_KEY=

Paste your keys from the JSON file in here.

Awesome! Now you are ready to start integrating google sheets like I did here to store Newsletter subscribers from another nextjs app!

Happy coding! 😊

Fastest way to start a new project with Nextjs & Sanity CMS & pnpm

Julian Bustos — Tue, 10 Jun 2025 02:31:22 +0000

pnpm create next-app@latest my-new-app

Select your nextjs options
cd into your app

cd my-new-app

Create a new sanity project, embed the studio and create all the config files, from the cli

pnpm dlx sanity@latest init --create-project "My New App" --dataset production

Select your configuration options for your sanity project as well as the route for the embedded studio.

Optional Steps

Add the scripts to generate types from your schemas and queries, to your package.json.

    "updateSchemaTypes": "sanity schema extract --enforce-required-fields",
    "generateQueryTypes": "sanity typegen generate",
    "generateTypes": "pnpm updateSchemaTypes && pnpm generateQueryTypes",

Now you can run pnpm generateTypes every time you update your schemas or add a new query using defineQuery function from next-sanity, and you can get typed queries.

Now you're all setup and ready to go!

Happy coding!

Use Next.js 14 (App Router) to Store Subscriber Info in Google Sheets for FREE

Julian Bustos — Fri, 20 Sep 2024 19:34:06 +0000

Introduction

In this tutorial, we will learn how to store user input from a Next.js app into a Google Sheets spreadsheet.

Requirements

Google Sheets Setup
A running Next.js App

I will start with a clean project, but I assume you already have a Next.js app up and running. Below is what I have in my layout.tsx, globals.css, and home page files:

// app/layout.tsx

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "Nextjs Google Sheets Integration",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className="antialiased"
      >
        {children}
      </body>
    </html>
  );
}

 /* app/global.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

// app/page.tsx

export default function Home() {
  return (
    <main>
      <h1>Nextjs Google Sheets Integration</h1>
    </main>
  );
}

Now let's setup google so we can use it as our backend for our subscribers.

Google Setup

We will first need to create a new Service Account to do so go here

Click on Start Free

Read the terms of service and click Agree & Continue.

Create your Payment Profile (you won't be charged).
Select Individual Profile Type if you're not a business.
Click Create.
Now add a payment method.
Click Start Free.
Select your Cloud Platform options.

Great! Now that we have a Service Account set up, look for the menu on the left and click on APIs & Services.

Enable APIs & Services

Search for Google Sheets API and select it

Click Enable

Great now we have the google sheets API enabled now let's create the credentials so we can programmatically connect to it.

Click on Create Credentials

Select Application Data & click Done

Now click on the IAM & Admin in the left menu and then click Service Accounts

Now click on Create Service Account

Give your account a name and a description and click Create And Continue

Select Owner as the Role and click Continue

We can click Done on the final step.

Now we can manage the keys for this account which will allow us to connect to Google Sheets.

Click on the 3 dots and select Manage Keys

Click on Add Key and then on Create new key

Select the JSON option and click Create

Save it somewhere safe and then open it in your code editor

Great all we really care about are the private_key and the client_email, these will allow us to establish the connection.

Go back to your Nextjs Project and in the .env.local (if you don't have a .env file yet create one in the root of your project) file let's create the environment variables we will need.

# .env.local

GOOGLE_SERVICE_ACCOUNT_EMAIL=
GOOGLE_PRIVATE_KEY=

Paste your keys from the JSON file in here.

Awesome! Now we are ready to start writing some code finally!

Let's run our app

pnpm dev

And open it in the browser.

We are going to create a button that opens a Dialog with the subscription form.

Lets start by adding the SubscribeDialog component.

Create Subscribe.tsx and import it in your page.tsx

We'll copy some basic styles for the buttons from tailwindcss.com

We will also use a dialog element so we can take advantage of some default behaviour that we'll see in action later, we have to give it the open property so we can see it on the screen, and some basic layout styles.

If we remove the open prop you will see the content change.

// app/Subscribe.tsx
const Subscribe = () => {
  return (
    <>
      <button className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent rounded">
        Subscribe
      </button>

      <dialog open className="border border-black py-5 px-3">
        <form className="flex flex-col gap-2">
          <label htmlFor="email">
            <span>Email: </span>
            <input type="email" id="email" name="email" className="border border-black" />
          </label>
          <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent rounded">Subscribe</button>
        </form>
      </dialog>
    </>
  );
}

export default Subscribe;

Call it in page.tsx

// app/page.tsx

import Subscribe from "./Subscribe";

export default function Home() {
  return (
    <main className="flex flex-col items-center justify-center min-h-[100dvh]">
      <h1>Nextjs Google Sheets Integration</h1>
      <Subscribe />
    </main>
  );
}

Now we can add the functionality to the button so we can open and close the dialog.

We will need to use the useRef hook which means we will need to make this component into a client component.

We will also write a toggleDialog function so we can open and close the dialog, and we will also add a close button to the dialog so we can close it. However because we are using the dialog and the showModal javascript function, it means we can use the ESC key to close the modal as well.

// app/Subscribe.tsx

"use client";

import { useRef } from "react";

const Subscribe = () => {

  const dialogRef = useRef<HTMLDialogElement>(null);
  const toggleDialog = () => {
    if (dialogRef.current?.open) {
      return dialogRef.current?.close();
    }
    dialogRef.current?.showModal();
  }

  return (
    <>
      <button onClick={toggleDialog} className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">
        Subscribe
      </button>

      <dialog ref={dialogRef} className="border border-black py-10 px-3 backdrop:bg-black backdrop:opacity-70">
        <form className="flex flex-col gap-2">
          <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
          <label htmlFor="email">
            <span>Email: </span>
            <input type="email" id="email" name="email" className="border border-black" />
          </label>
          <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">Subscribe</button>
        </form>
      </dialog>
    </>
  );
}

export default Subscribe;

Nice! But we also want to capture more than the users email, however in my case I just want first name and last name.

// app.Subscribe.tsx

"use client";

import { useRef } from "react";

const Subscribe = () => {

  const dialogRef = useRef<HTMLDialogElement>(null);
  const toggleDialog = () => {
    if (dialogRef.current?.open) {
      return dialogRef.current?.close();
    }
    dialogRef.current?.showModal();
  }

  return (
    <>
      <button onClick={toggleDialog} className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">
        Subscribe
      </button>

      <dialog ref={dialogRef} className="border border-black pt-10 pb-5 px-3 backdrop:bg-black backdrop:opacity-70">
        <form className="flex flex-col gap-2">
          <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
          <label htmlFor="email">
            <span>Email: </span>
          </label>
          <input type="email" id="email" name="email" className="border border-black" />
          <label htmlFor="firstName">
            <span>First Name: </span>
          </label>
          <input type="firstName" id="firstName" name="firstName" className="border border-black" />
          <label htmlFor="lastName">
            <span>Last Name: </span>
          </label>
          <input type="lastName" id="lastName" name="lastName" className="border border-black" />
          <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">Subscribe</button>
        </form>
      </dialog>
    </>
  );
}

export default Subscribe;

Great! Now that we have a front end let's write a form action for us to safely store the user's information on the backend. We will use valibot to validate the user data and the google API package to store the data.

Let's add the googleapis package first.

pnpm add googleapis

Create the action file, I'm going to call it subscribeAction, which will receive our form data and store it, so let's start by receiving the form data. To make it safe we will use a "use server" directive at the top of the file.

// app/subscribeAction.ts

"use server";

export const subscribeAction = async (formData: FormData) => {
  const rawData = {
    email: formData.get("email"),
    firstName: formData.get("firstName"),
    lastName: formData.get("lastName"),
  }

  console.log({rawData})
};

And we have to call our function, in our form like this:

// app/Subscribe.ts
import { subscribeAction } from "./subscribeAction";

// ... rest of your code
        <form className="flex flex-col gap-2" action={subscribeAction}>
// ... rest of your code

Now you should be able to see the console log when you click the subscribe button.

Awesome let's add valibot now so we can validate the data. (valibot is a smaller zod which will help you add types and validations and errors to show) valibot uses a slightly different approach than zod, if we want to run different validations on a single piece of data we need to create pipes, and then we can add any validations we need. Feel free to go to their docs to learn more.

Let's do that first

pnpm add valibot

It's best to write your validations in a separate file in case you need to call the types on the front-end. I'm going to call this file valibotSchemas.ts.

// app/valibotSchemas.ts
import { email, maxLength, nonEmpty, object, pipe, string } from "valibot";

export const subscribeDataSchema = object({
  email: pipe(
    string(),
    nonEmpty("Please enter your email."),
    email("The email is badly formatted."),
    maxLength(30, "Your email is too long.")
  ),
  firstName: pipe( 
    string(),
    nonEmpty("Please enter your first name."),
    maxLength(30, "Your first name is too long.")
  ),
  lastName: pipe( 
    string(),
    nonEmpty("Please enter your last name."),
    maxLength(30, "Your first name is too long.")
  ),
});

Now we can import it so we can validate our data and get sweet type safety too.

// app/subscribeAction.ts
"use server";

import { parse, ValiError } from "valibot";
import { subscribeDataSchema } from "./valibotSchemas";

export const subscribeAction = async (formData: FormData) => {
  const rawData = {
    email: formData.get("email"),
    firstName: formData.get("firstName"),
    lastName: formData.get("lastName"),
  };
  try {
    const data = parse(subscribeDataSchema, rawData);
    console.log({ data });
  } catch (error: unknown) {
    if (error instanceof ValiError) {
      const issues = error.issues;
      const errorMessages = issues.map((issue) => issue.message);
      console.log({ errorMessages });
    } else {
      console.log({ error });
    }
  }
};

Now if you an empty value on your form and click subscribe and look at your console you will see the error messages, we will use these to let the user know if there is an issue. To do this we will use React's useFormState hook.

We will add the useFOrmState and replace the action in our form in our Subscribe component.

"use client";

import { useRef } from "react";
import { subscribeAction } from "./subscribeAction";
import { useFormState } from "react-dom";

const Subscribe = () => {
  const [formState, formAction] = useFormState(subscribeAction, {
    success: false,
    errors: null,
  });

  const dialogRef = useRef<HTMLDialogElement>(null);
  const toggleDialog = () => {
    if (dialogRef.current?.open) {
      return dialogRef.current?.close();
    }
    dialogRef.current?.showModal();
  }

  return (
    <>
      <button onClick={toggleDialog} className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">
        Subscribe
      </button>

      <dialog ref={dialogRef} className="border border-black pt-10 pb-5 px-3 backdrop:bg-black backdrop:opacity-70">
        <form className="flex flex-col gap-2" action={formAction}>
          <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
          <label htmlFor="email">
            <span>Email: </span>
          </label>
          <input type="email" id="email" name="email" className="border border-black" />
          <label htmlFor="firstName">
            <span>First Name: </span>
          </label>
          <input type="firstName" id="firstName" name="firstName" className="border border-black" />
          <label htmlFor="lastName">
            <span>Last Name: </span>
          </label>
          <input type="lastName" id="lastName" name="lastName" className="border border-black" />
          <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">Subscribe</button>
        </form>
      </dialog>
    </>
  );
}

export default Subscribe;

Now typescript is unhappy with out subscribe function because the action now needs to receive the formState, and also the returns of our function don't match the expected return defined in our form action ({ success: false, errors: null}) so let's add fix that.

Since we are not going to use we can just leave it empty.

// app/subscribeAction.ts
"use server";

import { parse, ValiError } from "valibot";
import { subscribeDataSchema } from "./valibotSchemas";

export const subscribeAction = async (state: {}, formData: FormData) => {
  const rawData = {
    email: formData.get("email"),
    firstName: formData.get("firstName"),
    lastName: formData.get("lastName"),
  };

  try {
    const data = parse(subscribeDataSchema, rawData);
    console.log({ data });

    return {
      success: true,
      errors: null,
    };
  } catch (error: unknown) {
    if (error instanceof ValiError) {
      const issues = error.issues;
      const errorMessages = issues.map((issue) => issue.message);

      console.log({ errorMessages });

      return {
        success: false,
        errors: errorMessages,
      };
    } else {
      console.log({ error });
      return {
        success: false,
        errors: ["An error occurred."],
      };
    }
  }
};

And now on our Subscribe component let's render those messages if we have any.

// app/Subscribe.tsx
"use client";

import { useRef } from "react";
import { subscribeAction } from "./subscribeAction";
import { useFormState } from "react-dom";

const Subscribe = () => {
  const [formState, formAction] = useFormState(subscribeAction, {
    success: false,
    errors: null,
  });

  const dialogRef = useRef<HTMLDialogElement>(null);
  const toggleDialog = () => {
    if (dialogRef.current?.open) {
      return dialogRef.current?.close();
    }
    dialogRef.current?.showModal();
  }

  return (
    <>
      <button onClick={toggleDialog} className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">
        Subscribe
      </button>

      <dialog ref={dialogRef} className="border border-black pt-10 pb-5 px-3 backdrop:bg-black backdrop:opacity-70">
        <form className="flex flex-col gap-2" action={formAction}>
          <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
          <label htmlFor="email">
            <span>Email: </span>
          </label>
          <input type="email" id="email" name="email" className="border border-black" />
          <label htmlFor="firstName">
            <span>First Name: </span>
          </label>
          <input type="firstName" id="firstName" name="firstName" className="border border-black" />
          <label htmlFor="lastName">
            <span>Last Name: </span>
          </label>
          <input type="lastName" id="lastName" name="lastName" className="border border-black" />
          <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">Subscribe</button>
          {formState.errors?.map((error) => (
            <span className="text-red-700">
              *{error}
            </span>
          ))}
        </form>
      </dialog>
    </>
  );
}

export default Subscribe;

Great! Now that we have dealt with the errors let's work on storing our data on a google spreadsheet. We have not yet created one so let's go ahead and do that. Go to Google Sheets and Create a new Blank Spreadsheet

Let's add titles to the first row, in my case A will be email, B will be first name, and C will be last name.

On the spreadsheet for ease of reading later.

Lastly, we will add the google Service Account email to the users allowed to edit the document. Click on Share.

Add the Service Email we added to the .env.local and give it editor access.

Click Send

We will need this spreadsheet's id in order to connect to it.

The id of the spreadsheet is in the URL, it is everything between /d/ and /edit rest of URL.

..../spreadsheets/d/<>/edit......

Copy it and let's head back to our .env.local and add it in there. I will call this environment variable GOOGLE_SPREADSHEET_ID. Remember to restart your server after adding anything to your .env.local.

Now we can create a function that will return the google auth so we can use it in other places too.

Let's create a new file for that, I will call it googleAuth.ts

// app/googleAuth.ts
import { google } from "googleapis";

export const googleAuth = async () => {
  const clientEmail = process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL;
  const privateKey = process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, "\n");

  if (!clientEmail || !privateKey) {
    throw new Error("Missing Google credentials.");
  }

  return new google.auth.GoogleAuth({
    credentials: {
      client_email: clientEmail,
      private_key: privateKey,
    },
    scopes: [
      "https://www.googleapis.com/auth/drive",
      "https://www.googleapis.com/auth/drive.file",
      "https://www.googleapis.com/auth/spreadsheets",
    ],
  });
};

Great now let's update our action and finally store some data on our sheet.

// app/subscribeAction.ts
"use server";

import { parse, ValiError } from "valibot";
import { subscribeDataSchema } from "./valibotSchemas";
import { googleAuth } from "./googleSpreadsheets";
import { google } from "googleapis";

export const subscribeAction = async (state: {}, formData: FormData) => {

  const spreadsheetId = process.env.GOOGLE_SPREADSHEET_ID;

  if (!spreadsheetId) {
    return {
      success: false,
      errors: ["There was an error connecting to google."],
    };
  }

  const rawData = {
    email: formData.get("email"),
    firstName: formData.get("firstName"),
    lastName: formData.get("lastName"),
  };

  try {
    const data = parse(subscribeDataSchema, rawData);

    const sheets = await google.sheets({
      auth: await googleAuth(),
      version: "v4",
    });

    await sheets.spreadsheets.values.append({
      spreadsheetId,
      range: "A1:C1",
      valueInputOption: "USER_ENTERED",
      requestBody: {
        values: [[data.email, data.firstName, data.lastName]],
      },
    });

    return {
      success: true,
      errors: null,
    };
  } catch (error: unknown) {
    if (error instanceof ValiError) {
      const issues = error.issues;
      const errorMessages = issues.map((issue) => issue.message);

      return {
        success: false,
        errors: errorMessages,
      };
    } else {
      console.error(error);
      return {
        success: false,
        errors: ["An error occurred."],
      };
    }
  }
};

Now check your spreadsheet and make sure you were able to add the information correctly. If you get any errors make sure your environment variables don't have any typos.

If you get an unauthorized message you might have missed the sharing the spreadsheet with the service account step. Go back to the Google Setup section.

Awesome, now that we are storing data, we want to make sure we don't add any repeats and that we get a success message if the information was added correctly.

Let's work on the no email repeats part first.

// app/subscribeAction.ts

"use server";

import { parse, ValiError } from "valibot";
import { subscribeDataSchema } from "./valibotSchemas";
import { googleAuth } from "./googleAuth";
import { google } from "googleapis";

export const subscribeAction = async (state: {}, formData: FormData) => {

  const spreadsheetId = process.env.GOOGLE_SPREADSHEET_ID;

  if (!spreadsheetId) {
    return {
      success: false,
      errors: ["There was an error connecting to google."],
    };
  }

  const rawData = {
    email: formData.get("email"),
    firstName: formData.get("firstName"),
    lastName: formData.get("lastName"),
  };

  try {
    const data = parse(subscribeDataSchema, rawData);

    const sheets = await google.sheets({
      auth: await googleAuth(),
      version: "v4",
    });

    // Select spreadsheet the range to read my emails are on column A
    const readRange = "A1:A";

    // Get the emails from the spreadsheet
    const emails = await sheets.spreadsheets.values.get({
      spreadsheetId: process.env.GOOGLE_SPREADSHEET_ID,
      range: readRange,
    });

    // Check if the email already exists
    const emailExists = emails.data.values?.flat().includes(data.email);

    if (emailExists) {
      return {
        success: false,
        errors: ["You're already subscribed!"],
      };
    };

    await sheets.spreadsheets.values.append({
      spreadsheetId,
      range: "A1:C1",
      valueInputOption: "USER_ENTERED",
      requestBody: {
        values: [[data.email, data.firstName, data.lastName]],
      },
    });

    return {
      success: true,
      errors: null,
    };

  } catch (error: unknown) {

    if (error instanceof ValiError) {

      const issues = error.issues;
      const errorMessages = issues.map((issue) => issue.message);

      return {
        success: false,
        errors: errorMessages,
      };

    } else {
      return {
        success: false,
        errors: ["An error occurred."],
      };
    }
  }
};

Great now we should be able to see a message if the user is already in our spreadsheet.

Now let's add a small success message.

// app/Subscribe.tsx
"use client";

import { useRef } from "react";
import { subscribeAction } from "./subscribeAction";
import { useFormState } from "react-dom";

const Subscribe = () => {
  const [formState, formAction] = useFormState(subscribeAction, {
    success: false,
    errors: null,
  });

  const dialogRef = useRef<HTMLDialogElement>(null);
  const toggleDialog = () => {
    if (dialogRef.current?.open) {
      return dialogRef.current?.close();
    }
    dialogRef.current?.showModal();
  }

  return (
    <>
      <button onClick={toggleDialog} className="bg-transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">
        Subscribe
      </button>

      <dialog ref={dialogRef} className="border border-black pt-10 pb-5 px-3 backdrop:bg-black backdrop:opacity-70">
        {formState.success ? (
          <div>
            <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
            <h2>Thank you for subscribing!</h2>
          </div>
        ) : (
          <form className="flex flex-col gap-2" action={formAction}>
            <button onClick={toggleDialog} className="absolute right-2 top-2">X</button>
            <label htmlFor="email">
              <span>Email: </span>
            </label>
            <input type="email" id="email" name="email" className="border border-black" />
            <label htmlFor="firstName">
              <span>First Name: </span>
            </label>
            <input type="firstName" id="firstName" name="firstName" className="border border-black" />
            <label htmlFor="lastName">
              <span>Last Name: </span>
            </label>
            <input type="lastName" id="lastName" name="lastName" className="border border-black" />
            <button type="submit" className="transparent hover:bg-green-500 text-green-700 font-semibold hover:text-white py-2 px-4 border border-green-500 hover:border-transparent">Subscribe</button>
            {formState.errors?.map((error) => (
              <span className="text-red-700">
                *{error}
              </span>
            ))}
          </form>
        )}
      </dialog>
    </>
  );
}

export default Subscribe;

And just like that, we're done! Now you know how to use Google Sheets to store data, which you could use as a lightweight CMS or even a simple database.

I hope you learned something valuable from this tutorial. Feel free to leave any comments or ask any questions!

Julian Bustos

How to Create a Custom Deploy (Vercel/Netlify) Button for your Sanity Project

Julian Bustos — Thu, 05 Sep 2024 15:53:17 +0000

Deploying a Sanity project to Vercel or Netlify has never been easier, thanks to their deploy hooks. But what if you want to take it a step further and create a custom deploy button that suits your unique project setup? In this guide, we’ll walk you through the process of creating a custom deploy button tailored specifically for your Sanity project, ensuring a seamless deployment experience for you and your team.

What you will need

Assuming you have a Next.js site with Sanity CMS v3 integrated, you’ll need a few essentials to create a custom deploy button. First, obtain a deploy hook URL from your deployment provider, which in this case is Vercel. This URL will be used to trigger the redeployment of your project whenever the button is clicked. Additionally, ensure you have a running Sanity CMS project, specifically version 3, as this guide will focus on building the custom button for this version of Sanity. With these components in place, you’ll be able to set up a streamlined deployment workflow tailored to your project.

We will also need to add the @sanity/ui library
npm install @sanity/ui

Adding a Custom Deploy Button to the Sanity Dashboard

The goal is to have a deploy button conveniently located on the top right corner of your Sanity dashboard. To achieve this, we’ll need to customize the Sanity navbar by creating a custom navigation component. Sanity allows us to extend the default UI, so we’ll make use of that flexibility to insert our deploy button.

Let’s start by creating a custom navigation component. This component will be responsible for adding the button to the navbar, allowing users to trigger a deployment directly from within the dashboard. Here's how to get started with the custom navbar component.

We'll first just render the custom sanity navbar as we just want to add to it.

I like to keep my sanity code in one place and I have a directory called components. Inside of it we can create our file CustomNavbar.tsx

// sanity/components/CustomNavbar.tsx
import { NavbarProps } from "sanity";

export function CustomNavbar(props: NavbarProps) {
  const { renderDefault } = props;

  return (
    <>
      {renderDefault(props)}
    </>
  )
}

It won't work without implementing it, so let's import it in our sanity config. We can add to the studio dashboard custom components.

// sanityConfig.ts
import { CustomNavbar } from "./components/NewCustomNavbar";

export const sanityAdminConfig = {
  projectId: process.env.SANITY_PROJECT_ID || "",
  dataset,
  useCdn: process.env.NODE_ENV === "production",
  title: "Your Site Title",
  apiVersion: "2021-10-21",
  basePath: "/studio", // hosted studio path
  plugins: [
  ],
  schema: {
    // your schemas
  },
};

export const studioConfig = defineConfig({
  ...sanityAdminConfig,
  studio: {
    components: {
      navbar: CustomNavbar,
    },
  },
});

Awesome! Now let's add a button to our nav, and let's add some sanity UI elements to our nav to make it look better.

import { Box, Button, Flex } from "@sanity/ui";
import { NavbarProps } from "sanity";

export function CustomNavbar(props: NavbarProps) {
  const { renderDefault } = props;

  return (
    <Flex align="center">
      <Box flex={1}>
        {renderDefault(props)}
      </Box>
      <Button
        tone="positive"
        mode="ghost"
        style={{
          height: "100%",
          borderRadius: 0,
        }}
      >
        Deploy
      </Button>
    </Flex>
  )
}

Great! Now let's prepare a function to trigger our deploy hook, and we can add sanity's toasts to give appropriate messages to the the user.

Here we'll need to add our deploy hook, I stored it in my env as NEXT_PUBLIC_DEPLOY_HOOK.

Since we are using the toast to give messages we will need to declare this function inside of our custom nav component.

// sanity/components/CustomNavbar.tsx
import { Box, Button, Flex, useToast } from "@sanity/ui";

export function CustomNavbar(props: NavbarProps) {
  // ... rest of your code
  const toast = useToast();
  const deployHookUrl = process.env.NEXT_PUBLIC_DEPLOY_HOOK;

  const deploySite = async () => {

    if (!deployHookUrl) {
      toast.push({
        status: 'error',
        title: 'Deployment Failed',
        description: 'No Vercel deploy hook found. Please check your environment variables.',
      });
      return;
    }

    try {
      const response = await fetch(deployHookUrl, {
        method: 'POST',
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      toast.push({
        status: 'success',
        title: 'Deployment Triggered',
        description: 'Deployment has been triggered successfully. It may take a few minutes to complete.',
      });
    } catch (error) {
      console.error('Deployment failed:', error);
      toast.push({
        status: 'error',
        title: 'Deployment Failed',
        description: error instanceof Error ? error.message : 'An unknown error occurred',
      });
    }
  };
  return (
    <Flex align="center">
      <Box flex={1}>
        {renderDefault(props)}
      </Box>
      <Button
        tone="positive"
        mode="ghost"
        style={{
          height: "100%",
          borderRadius: 0,
        }}
      >
        Deploy
      </Button>
    </Flex>
  )
}

Great now lets prepare a handleDeploy function that we can call in our button. We will do this so we can trigger a timeout in the end and give our users some messages and enable and disable the button. We will also add a state to keep track of wether we are deploying or not.

export function CustomNavbar(props: NavbarProps) {
  // ... rest of your code
    const [isDeploying, setIsDeploying] = useState(false);

      const handleDeploy = async () => {
    setIsDeploying(true);
    await deploySite();

    // Re-enable the button after 1 minute
    setTimeout(() => {
      setIsDeploying(false);
    }, 60000); // 60000 ms = 1 minute
  };
  return (
    <Flex align="center">
      <Box flex={1}>
        {renderDefault(props)}
      </Box>
      <Button
        onClick={handleDeploy}
        disabled={isDeploying}

        tone="positive"
        mode="ghost"
        style={{
          height: "100%",
          borderRadius: 0,
        }}
      >
        {isDeploying ? 'Deploying...' : 'Deploy'}

      </Button>
    </Flex>
  )
}

The reason we are using setTimeout is that, unfortunately, there isn't a built-in way to listen for the completion of the build process directly. This workaround ensures that the deployment is triggered effectively from within your Sanity CMS project without relying on third-party applications.

If you have any suggestions or methods for monitoring the build state changes more accurately, I would love to hear your thoughts or read about it.

Thank you for reading, and I hope you found this guide useful for enhancing your deployment workflow.

How to duplicate a Sanity Dataset for FREE

Julian Bustos — Thu, 04 Apr 2024 17:56:21 +0000

Updating a website's backend can be nerve-wracking, especially when the site is live. Introducing new features often requires code changes, and there's always a risk of something breaking unintentionally. This article explores a cost-effective way to avoid disrupting your Sanity CMS backed site during development by creating a separate development dataset.

Have you ever screwed up your own site, because you were working on something else?

I have a couple of times, and sometimes It's understandable because you are working on fixing it and no one is looking at it. Sometimes it's more important.

I am at that point where it matters, my client wants to start updating the backend with the content, and I'm trying to write code to implement the latest features requested.

An update that for a small bit of time would break the site. The good news is, it doesn't have to. If we split our datasets and we do our development on another dataset we can avoid issues like these. But I also want all the content that's already on the site.

When you look up the Sanity documentation you'll come across a very handy option to copy the dataset into another dataset, but when you run it you this functionality requires a paid plan. However, you could do this for free too if we export the dataset and then import it into the new dataset, just a couple more steps.

Check sanity version or install a the cli tool.

npm install --global sanity@latest

# Alternatively
yarn global add sanity@latest
pnpm install --global sanity@latest

# Running the CLI without global installation
npx -y sanity@latest [command]

sanity login

Remember to login with the correct user 😅.
Setup your cli env.
In the root of your project create a file called sanity.cli.ts or sanity.cli.js with the following content:

// sanity.cli.ts
import { defineCliConfig } from "sanity/cli";

export default defineCliConfig({
  api: {
    projectId: "<your-project-id>",
  }
});

cd into the root of your project
Export your dataset

sanity dataset export <dataset-name> <export-file.tar.gz> [--types <type1,type2,...>]

dataset-name: Replace this with the actual name of the dataset you want to export (e.g., "production").
export-file.tar.gz: Specify the desired filename and location for the exported data archive (e.g., "my-data.tar.gz").
--types (optional): This flag allows you to export specific document types only. Separate multiple types with commas (e.g., "--types post, product").

in my case this means:

sanity dataset export production production-file.tar.gz

when its done we can now create the new dataset.

sanity dataset create development

select your choice, for me this is a public dataset as it's going to be used for development only.
import your downloaded file into your dataset

sanity dataset import [FILE | FOLDER | URL] [TARGET_DATASET]

for me that's going to be:

sanity dataset import production-file.tar.gz development

Once done you have duplicated or copied your dataset for FREE!

Setup a SANITY_DATASET environment variable in your env file.

//.env.local
SANITY_DATASET=development

Update your sanity config file.

// sanity.config.ts
export const studioConfig = defineConfig({
  //...rest of your config
  dataset: process.env.SANITY_DATASET || "",
})

If you have a deployed version of the site you will want to update the environment variables of your deployed site.
You probably will want to delete that file from your project root, or store it somewhere else.

Thank you for reading!

How to add user auth with Clerk to Nextjs (App Directory) and store it in Embedded Sanity CMS

Julian Bustos — Mon, 14 Aug 2023 18:32:34 +0000

How to add user auth with Clerk to Nextjs (App Directory) and store it in Sanity CMS

First we are going to install a new Nextjs project but this should work with any Nextjs App Directory project, then we will install Clerk and get it working, once it’s working we will install and embed a Sanity studio and get it ready to receive the information provided by Clerk. We will finish by creating an API route, where we will send the user data to Sanity, and verify that the user was created.

Install Nextjs in an empty folder.

npx create-next-app@latest .

Proceed with you favourite settings I will choose Tailwind, Typescript, and the App Directory.

For the purpose of this tutorial I want to start with an empty home page in app/page.tsx.

// app/page.tsx
const Home = () => {
  return (
    <main className="grid place-content-center min-h-screen">
      Hello World
    </main>
  )
}

export default Home;

Run the project and verify everything is working

npm run dev

Install Clerk and dependencies.

npm install @clerk/nextjs

Go to www.clerk.com and sign-up for a free account.
Once inside click on Add Application and give it a name
Select your favorite sign-in providers. I will choose email and Google.

Copy the API Keys and paste them into your .env.local file.
Mount ClerkProvider Update your root layout to include the wrapper. The component wraps your Next.js application to provide active session and user context to Clerk's hooks and other components. It is recommended that the wraps the to enable the context to be accessible anywhere within the app.
Your app/layout.tsx should look something like this:

// app/layout.tsx
import './globals.css'
import { Inter } from 'next/font/google'
import { ClerkProvider } from '@clerk/nextjs'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body className={inter.className}>{children}</body>
      </html>
    </ClerkProvider>
  )

Protect your Application

Now that Clerk is installed and mounted in your application, it’s time to decide which pages are public and which need to hide behind authentication. We do this by creating a middleware.ts file at the root folder (or inside src/ if that is how you set up your app).

In my case I will create the middleware.ts file inside the root folder of my project. I will also add a Public Routes array, so any route you would like to be public you will need to add to this array.

We will add the studio route, and let sanity handle the auth for the CMS studio.

// middlewate.ts
import { authMiddleware } from "@clerk/nextjs";

// This example protects all routes including api/trpc routes
// Please edit this to allow other routes to be public as needed.
// See https://clerk.com/docs/nextjs/middleware for more information about configuring your middleware

const publicRoutes = ["/", "/studio"];

export default authMiddleware({
  publicRoutes,
});

export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};

Create the sign-up page.

In the app directory create a sign-up folder and then another catch-all [[…sign-up]] folder with a page inside of it. Your route should look like this: app/sign-up/[[…sign-up]]/page.tsx

Inside the page.tsx file we will add the provided SignUp component from Clerk.
```
// app/sign-up/[[…sign-up]]/page.tsx

import { SignUp } from "@clerk/nextjs";

export default function Page() {
  return (
    <main className="grid place-content-center min-h-screen">
      <SignUp/>
    </main>
  );
}
```
Do the same for the Sign in page. But we will also add the redirectUrl parameter provided by nextjs so that the user can be redirected back to the page they were visiting before or home if there isn’t any.

// app/sign-up/[[…sign-in]]/page.tsx

import { SignIn } from "@clerk/nextjs";

export default function Page({searchParams}: {searchParams: {redirectUrl: string | undefined}}) {
  const {redirectUrl} = searchParams;
  return (
    <main className="grid place-content-center min-h-screen">
      <SignIn redirectUrl={redirectUrl || "/"}/>
    </main>
  );
}

Next we will add some more environment variables to control the behavior of clerk and also to tell it what route the sign-up and sign-in pages are in, we do this in the .env.local file in the root right after our API keys.

// .env.local

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

Create a link to the sign up page inside the homepage. In app/page.tsx lets add the link

Run the app, navigate to http://localhost:3000 using the browser and click on sign-up, sign-up for your app.

// app/page.tsx
import Link from "next/link";

const Home = () => {
  return (
    <main className="grid place-content-center min-h-screen">
      <Link href="/sign-up">Sign Up</Link>
    </main>
  );
};

export default Home;

Go to dashboard.clerk.com select your project and verify your new user.
In the homepage let’s add some user data to the home page and some conditional rendering to see the data if the user is logged in.

// app/page.tsx

import { UserButton, currentUser } from "@clerk/nextjs";
import Link from "next/link";
export default async function Home() {
  const user = await currentUser();

  if (user) {
    return (
      <main className="grid place-content-center gap-2 min-h-screen">
        <div className="flex items-center gap-2">
          <UserButton afterSignOutUrl="/" />
          <h2>Welcome back {user.firstName}!</h2>
        </div>
      </main>
    );
  }
  return (
    <main className="grid place-content-center min-h-screen">
      <Link href="/sign-up">Sign Up</Link>
    </main>
  );
}

Let’s visit our homepage:

If we click on the user image we have access to some options, for now I will try to sign out to see the other view.

You should see your sign-up button now:

We can also add a signout button provided by clerk to make it easier to sign out and clearer that its a sign up / sign in page as well:

//// app/page.tsx
import { currentUser, UserButton, SignOutButton } from "@clerk/nextjs";
import Link from "next/link";
export default async function Home() {
  const user = await currentUser();

  if (user) {
    return (
      <main className="grid place-content-center gap-2 min-h-screen">
        <div className="flex items-center gap-2">
          <UserButton afterSignOutUrl="/" />
          <h2>Welcome back {user.firstName}!</h2>
          <SignOutButton />
        </div>
      </main>
    );
  }
  return (
    <main className="grid place-content-center min-h-screen">
      <Link href="/sign-up">Sign Up / Sign In</Link>
    </main>
  );
}

Now that we have sign up and sign out flows setup let’s create and embed a new sanity CMS in our Nextjs project, this process will still work even if the CMS isn’t embedded however I will embed a new project for the purpose of this tutorial.
Install the necessary packages for Sanity to work as well as the client packages to make the requests to the CMS.

npm install sanity next-sanity next-sanity-image @portabletext/react @sanity/client @sanity/image-url

Go to sanity.io sign up for an account. Sanity gives instructions on how to create the studio however since we are embedding the studio on a Nextjs project we can just ignore them and navigate to https://www.[sanity.io/manage](http://sanity.io/manage). If Sanity created a project for you click on it and copy the project ID, if they didn’t you can click on Create a new project on the top and then copy the project ID provided.
Go to your .env.local and add the project id under the Clerk variables like this:

/// .env.local
SANITY_PROJECT_ID=(your sanity project id)

Create a sanity folder on the root of your project, and a config.ts file with the following content:

// sanity/config.ts
export const sanityConfig = {
  projectId: process.env.SANITY_PROJECT_ID || "",
  dataset: 'production',
  useCdn: process.env.NODE_ENV === 'production',
  apiVersion: '2021-03-25',
}

Create your studioConfig.ts file inside the sanity folder in it for now we will define the config and the basePath for the sanity studio.

// sanity/studioConfig.ts
import { sanityConfig } from './config';
import { defineConfig } from "sanity";

export const sanityAdminConfig = {
  ...sanityConfig,
  title: "Clerk Users and Sanity Test",
  basePath: "/admin",
};

export const studioConfig = defineConfig(sanityAdminConfig);

Inside App directory create a page studio route and an index catch all filder, where we will mount the studio. app/studio/[[…index]]/page.tsx We will import the studio config we just created and give it as a prop to the NextStudio component provided by Sanity, this is Client component so we will have to add the use client directive at the top of the file.

// app/studio/[[…index]]/page.tsx
'use client'

import { studioConfig } from '@/sanity/studioConfig'
import {NextStudio} from 'next-sanity/studio'

export default function StudioPage() {
  //  Supports the same props as `import {Studio} from 'sanity'`, `config` is required
  return <NextStudio config={studioConfig} />
}

Lets restart our project by running npm run dev and navigate to http://localhost:3000/studio
We should get this error:

This is because we need to allow the route in the Sanity studio for it to be able to read and write to sanity’s database. We can add CORS origins in the Sanity Management Dashboard for the project.

Go to https://www.sanity.io/manage open the project we created previously and navigate to the API tab and look for the + Add CORS origin button

Add: http://localhost:3000, and click Allow Credentials since we are embedding the studio in our NextJS project we need to allow it to have credentials. When you deploy your site you will need to add the root address of your site ie: [http://www.yoursite.com](http://www.yoursite.com) to the list of allowed sites.

Click Save.
We can also delete localhost:3333 since this is the location of the default sanity studio which we are not using.

Go back to `http://localhost:3000/studio` and sign in with your user.

Now we have an empty studio embedded in the Nextjs site! Let’s add a users document list to our sanity.

Create the schema for the users, for our tutorial we will just need first name, last name, and email.
Create a schemas folder inside the sanity folder and create user.ts sanity/schemas/user.ts add the document for users, we will use an icon from sanity so that the users’ list gets a nice icon.

// sanity/schemas/user.ts

import { defineType, defineField } from "sanity";
import { UserIcon } from "@sanity/icons";

export const userSchema = defineType({
  name: "user",
  title: "Users",
  type: "document",
  icon: UserIcon,
  fields: [
    defineField({
      name: "firstName",
      title: "First Name",
      type: "string",
    }),
    defineField({
      name: "lastName",
      title: "Last Name",
      type: "string",
    }),
    defineField({
      name: "email",
      title: "Email",
      type: "string",
    })
  ],
});

Now lets add the schemas to our studioConfig. I like to keep my schemas organized in a separate file so that it’s easy to add or remove schemas from my project.

Create in the sanity folder a schemas.ts file. sanity/schema.ts and add the following:

// sanity/schema.ts

import {userSchema} from "./schemas/user";
export const schemaTypes = [
  userSchema
]

Import the schemas into the sanity/studioConfig.ts file and add it to the config.

// sanity/studioConfig.ts

import { sanityConfig } from './config';
import { defineConfig } from "sanity";
import { schemaTypes } from "./schemas";

export const sanityAdminConfig = {
  ...sanityConfig,
  title: "Clerk Users and Sanity Test",
  basePath: "/studio",
  schema: {
    types: schemaTypes,
  },
};

export const studioConfig = defineConfig(sanityAdminConfig);

We are still getting the same screen, that’s because I forgot to add the desktool to the config, let’s do that.

// sanity/studioConfig.ts 

import { sanityConfig } from './config';
import { defineConfig } from "sanity";
import { schemaTypes } from "./schemas";
import {deskTool} from "sanity/desk"

export const sanityAdminConfig = {
  ...sanityConfig,
  title: "Clerk Users and Sanity Test",
  basePath: "/studio",
  plugins: [
    deskTool(),
  ],
  schema: {
    types: schemaTypes,
  },
};

export const studioConfig = defineConfig(sanityAdminConfig);

Refresh, and we should be able to see the users list and we can add users to our list,

However, we want them to be added when the user signs in with our site. To do that we will use Clerks environment variables to redirect the user after sign-up to an API route, where we can get the user’s information add save it in our sanity and redirect the user again either to where they where coming from or to the homepage.

Let’s start by creating the API route first.

Create a folder create-sanity-user (you can name this something relevant to your app) inside the app folder and create a file route.tsx. This is a special Nextjs file that let’s us create api end points. app/create-sanity-user/route.ts, in it we will use clerk’s currentUser server function to access the user information. We also want to prevent anyone from accessing the route, so if the user doesn’t exist then we can redirect them to the sign-in page, however since we are using the middleware.ts file we won’t need to add that to our api route. Let’s try to return the user’s data first.

// app/create-sanity-user/route.ts

import { currentUser } from "@clerk/nextjs";
import { NextResponse } from "next/server";

export const GET = async () => {
  const user = await currentUser();
  return NextResponse.json({ user });
};

Navigate to http://localhost:3000/create-sanity-user we should now see the data that clerk gives you access too, we can save any of it in our sanity.
Navigate to [http://localhost:3000/](http://localhost:3000/) and log out and navigate back to http://localhost:3000/create-sanity-user` and we should now get redirected to the sign-in page! Great!
Let’s log back in and we should get redirected back to create-sanity-user end point.
Let’s now add the user data to sanity, we need to create a sanityClient file which will allow us to have access to sanity’s functionality, and be able to read and write data from our nextjs app.
We will also need an API token from sanity to be able to write data onto it. Go back to https://www.[sanity.io/manage](http://sanity.io/manage) and in the API tab click on + Add API token

Give it a name and select the Editor option to have access to read and write token options. Copy your token, and add it to your .env.local file.

jsx SANITY_API_TOKEN=(your api token)

Create in the sanity folder a sanityClient.ts file and import the createClient function from next-sanity, and your own config, and just add the token from the environment variables, or empty if it doesn’t exist.

`jsx
// sanity/sanityClient.ts

import { createClient } from "next-sanity";
import { sanityConfig } from "./config";
export default createClient({
...sanityConfig,
token: process.env.SANITY_API_TOKEN || "",
});
`

Go to the app/create-sanity-user/route.ts file and import the sanityClient we just created, we will use the createIfNotExists (which prevents errors when a user already exists) function that the next-sanity package provides to create a document in our sanity.
We are also going to get the base path URL to redirect to from the request, this will work for both development and deployed, since the NextResponse.redirect function expects a full url. And redirect the user to this base URL.
Even though the middleware is taking care of authentication, we still want to prevent typescript errors in case the user doesn’t exist.

`jsx
// app/create-sanity-user/route.ts

import { NextApiRequest } from "next";
import sanityClient from "@/sanity/sanityClient";
import { currentUser } from "@clerk/nextjs";
import { NextResponse } from "next/server";

export const GET = async (req: NextApiRequest) => {
const user = await currentUser();
if (!user) {
return NextResponse.redirect("/sign-in");
}

const {id, firstName, lastName, emailAddresses} = user;

await sanityClient.createIfNotExists({
_type: "user",
_id: id,
firstName,
lastName,
email: emailAddresses[0].emailAddress
})

const url = req.url?.split("/create-sanity-user")[0] || "/"
return NextResponse.redirect(url);
};
`

Restart your server and navigate to http://localhost:3000/create-sanity-user then navigate to your studio at `http://localhost:3000/studio` and see the new user has been added to your studio
The last step will be to update the NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL environment variable and point it to /create-sanity-user route to our environment variables so Clerk can have the right behavior after signing-up.

jsx NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/create-sanity-user

Restart your server since we updated the environment variables and try to signup with a different user, then check your studio and verify the new user was added.

That’s it, now you can add your own specific details to your users, or relate it to other documents specific for your use case.