Forem: Satomi Nagano / Akikaze1119

Automatically Send User Data to Database with Clerk OAuth

Satomi Nagano / Akikaze1119 — Mon, 27 Jan 2025 23:06:23 +0000

Key Points

Learn how to use Clerk webhooks.
Understand how to verify Clerk webhooks.
Use ngrok to expose a local endpoint for external access.

Background

When using Clerk OAuth for user authentication, detecting new user registrations from the web app can be challenging. To address this, we use Clerk webhooks to automatically send user data to a database upon signup. This article walks through the implementation steps.

Prerequisites

Using Clerk webhooks to send user data to a database upon signup.
The setup follows Clerk’s official documentation.
The database used is Neon (PostgreSQL).

Implementation Steps

1. Set Up ngrok

Clerk’s documentation recommends using ngrok to allow webhook requests to reach the local app.

1.1 Install and Set Up ngrok

1.2 Obtain an External URL

Start your local development server (npm run dev), then run

ngrok http [Port]

Example: In the case of http://localhost:3000

ngrok http 3000

Copy the Forwarding URL displayed.

What is ngrok?

Ngrok allows a locally running web app to be temporarily accessible over the internet. In this case, it enables Clerk webhooks to send requests to a local development server.

2. Configure Clerk Webhooks

2.1 Access Clerk Dashboard

Go to the Clerk dashboard.

2.2 Add a Webhook Endpoint

Navigate to the Webhooks tab and click Add Endpoint.
Set the Endpoint URL to the ngrok forwarding URL + /api/webhooks/user (e.g., https://example.ngrok-free.app/api/webhooks/user).
Add a description if needed.
Subscribe to the user.created event.
Click Create.

3. Add Signing Secret to `.env.local`

On the endpoint's settings page, copy the Signing Secret from the webhook settings.

Add Signing Secret, like SIGNING_SECRET=whsec_123, to your .env.local file, which should already include your Clerk API keys and DB URL.
The file should resemble:

DATABASE_URL=postgresql://database_url
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_YXdha2Utb3gtODUuY2xlcmsuYWNjb3VudHMuZGV2JA
CLERK_SECRET_KEY=sk_test_5DbmoNJeli74tMRgtzZLBY4SC6gpTLbNGnvAPeWJkE
SIGNING_SECRET=whsec_123

4. Make the Webhook Route Public

If using clerkMiddleware(), ensure that /api/webhooks(.*) is public. For information on configuring routes, see the clerkMiddleware() guide.

5. Install `svix`

Clerk uses svix to send signed webhook requests. Install it:

npm install svix

6. Create the Webhook API Route

Create /src/app/api/webhooks/user/route.ts to receive webhook requests:

import { NextResponse } from 'next/server';
import { Pool } from 'pg';

import { Webhook } from 'svix';
import { headers } from 'next/headers';
import { WebhookEvent } from '@clerk/nextjs/server';

// Initialize Neon DB connection
const pool = new Pool({
  connectionString: process.env.DATABASE_URL, // Add to .env
});

export async function POST(req: Request) {
  const SIGNING_SECRET = process.env.SIGNING_SECRET;

  if (!SIGNING_SECRET) {
    throw new Error('Error: Please add SIGNING_SECRET from Clerk Dashboard to .env or .env.local');
  }

  // Create new Svix instance with secret
  const wh = new Webhook(SIGNING_SECRET);

  // Get headers
  const headerPayload = await headers();
  const svix_id = headerPayload.get('svix-id');
  const svix_timestamp = headerPayload.get('svix-timestamp');
  const svix_signature = headerPayload.get('svix-signature');

  // If there are no headers, error out
  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response('Error: Missing Svix headers', {
      status: 400,
    });
  }

  // Get body
  const payload = await req.json();
  const body = JSON.stringify(payload);

  let evt: WebhookEvent;

  // Verify payload with headers
  try {
    evt = wh.verify(body, {
      'svix-id': svix_id,
      'svix-timestamp': svix_timestamp,
      'svix-signature': svix_signature,
    }) as WebhookEvent;
  } catch (err) {
    console.error('Error: Could not verify webhook:', err);
    return new Response('Error: Verification error', {
      status: 400,
    });
  }

  // Handling the user.created event (modify as needed)
  try {
    if (evt.type === 'user.created') {
      const { id } = evt.data;
      // Insert user into Neon DB
      await pool.query(
        `INSERT INTO users (user_id) VALUES ($1) 
        ON CONFLICT (user_id) DO NOTHING`,
        [id]
      );
      return NextResponse.json({ message: 'User saved to DB' }, { status: 200 });
    }

    return NextResponse.json({ message: 'Unhandled event' }, { status: 200 });
  } catch (error) {
    console.error('Webhook Error:', error);
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
  }
}

7. Test the Webhook

In the Clerk Webhook settings, go to Testing.
Select user.created from Send event.
Click Send Example.
If the request succeeds, it will be marked as Succeeded in Message Attempts

Therefore your app can automatically register new user information in the database even when using Clerk's OAuth. Please try registering a new user within the app to confirm that it works correctly.

Debugging Tips

If you encounter issues:

Check your Middleware configuration
Check your configuration in the Clerk Dashboard [For example] Directory: /src/app*/api/webhooks/user/route.ts* Endpoint in Clerk : http://.../api/webhooks/user
Test the Route Handler or API Route(following the guide) 1.Create a test route in your application:

▽app/webhooks/test/route.ts

export async function POST() {
  return Response.json({ message: 'The route is working' });
}

2.Run your application.
3.Use curl to test:

curl -H 'Content-Type: application/json' -X POST
http://localhost:3000/api/webhooks/test

4.If you see the {"message":"The route is working"}, then the basic Route Handler is working and ready to build on.

User deletion in Clerk

If you want to delete user information on Clerk, you can do so from the "User" tab.

Deploying

Add the webhook URL in Clerk with the production domain.
Add the Signing Secret to production environment variables.
Deploy your app.

Conclusion

Clerk webhooks enable real-time detection of new users.
Ngrok allows local webhook testing by exposing an accessible endpoint.
Implementing svix ensures request verification and security.

Understanding the Difference Between Imperative and Declarative Programming

Satomi Nagano / Akikaze1119 — Sun, 15 Sep 2024 06:01:44 +0000

When I first started learning React, my teacher said, "JavaScript is imperative programming, while React is declarative programming." However, this didn’t quite make sense to me at first. So, I decided to break it down to better understand the distinction.

Comparing Imperative and Declarative Programming with Pizza🍕

To make it easier to visualize, let’s compare these two approaches to cooking.

Imperative programming analogy:

It’s like giving a chef step-by-step instructions on how to make a pizza🍕.

Declarative programming analogy:

It’s like ordering a pizza without being concerned about the steps it takes to make the pizza🍕.

What is Imperative Programming?

Imperative programming is a style where the developer explicitly defines how to perform a specific task. You're writing the steps for how the user interface should be updated.

Example: Adding text to an h1 tag in HTML

const h1Element = document.createElement('h1');
h1Element.textContent = 'Hello, World!';
document.body.appendChild(h1Element);

In this code,

Manually creating the h1 element
Setting its text content
Appending it to the page Every individual step is written. This is a hallmark of imperative programming, where the developer must clearly define what the computer should do and how it should be done.

What is Declarative Programming?

In contrast, declarative programming focuses on what you want to achieve, without specifying how it should be done. The system handles the details for you.

Example: Adding text to an h1 tag (using React)

function App() {
  return (
    <h1>Hello, World!</h1>
  );
}

In this example, you’re simply declaring that an h1 element with the text "Hello, World!" should appear. The details of how it gets added to the DOM are handled by React. You only need to specify what you want to happen on the page, making declarative programming much more straightforward and efficient than the imperative approach.

Conclusion

Imperative programming involves specifying how things should be done, step by step.
Declarative programming focuses on what you want to accomplish.

Declarative libraries like React allow developers to express complex UI logic in simpler, more manageable terms, making the development process faster and more intuitive.

Reference: Next.js Tutorial

The pizza analogy is referenced from the Next.js tutorial

How to Deploy a Full-Stack Application on Vercel

Satomi Nagano / Akikaze1119 — Wed, 04 Sep 2024 22:03:59 +0000

In this article, I will guide you step by step on how to deploy a full-stack application using Vercel.

You can check the actual deployed project at the bottom of this article under the reference section.

Prerequisites

Before you start deploying, please ensure that you meet the following requirements:

You have a repository on GitHub, with separate frontend and backend folders
The connection between the frontend, backend, and the database is confirmed in the testing environment

Deploying the Backend to Vercel

Let's start by deploying the backend.

Step 1. Log in to Vercel

First, log in to Vercel or sign up if you haven't already.

Step 2. Add a New Project

Click the "Add New..." button in the red box and select "Project" from the dropdown.

Import an existing project from GitHub. If the target repository is displayed, select the "Import" button in the red box.

🚨If the target repository is not found, you may need to adjust the GitHub access settings. You can change the settings via the "Adjust GitHub App Permissions" link in the green box.

How to Adjust GitHub Repository Access Settings

Click the "Adjust GitHub App Permissions" link, select where to import from.

On the GitHub settings page, select the target repository from the "Repository access" dropdown and click Save. It should now appear in the Import list on Vercel.

Step 3. Configure the Project

Once the import is complete, configure the project.

Project Name:
It’s a good idea to add "backend" or "server" at the end of the project name.
(Example: "my-project-backend", "my-project-server", etc.)

A domain will be created using the name you set here plus ".vercel.app".
(Example: my-project-api.vercel.app, my-project-server.vercel.app, etc.)

Framework Preset:
Select "Others" from the dropdown.

Root Directory:
Click the "Edit" button and select the backend directory.

Build and Output Settings:
No settings are required here, but you can add any if needed.

Environment Variables:
Add the necessary environment variables here. (Note: PORT is not required.)

Deploy:
Once these settings are complete, click the "Deploy" button.

Step 4. Configure vercel.json

After deployment, add a vercel.json file to the root of the backend folder with the following content:

{
    "builds": [
        {
            "src": "*.js",
            "use": "@vercel/node"
        }
    ],
    "routes": [
        {
            "src": "/(.*)",
            "dest": "/"
        }
    ]
}

ℹ️ For TypeScript, specify it to read the compiled JS files. (In the example below, the TypeScript output directory ("outDir") is set to ./dist.)

{
  "builds": [
    {
      "src": "dist/server.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "dist/server.js"
    }
  ]
}

Step 5. Confirm Server Access

Check if you can access the deployed server. You can verify this from the "Domains" URL.

If the content of the file is displayed or if you see "Cannot GET /" on the page like this, it was successful! 🎉🎉🎉

🚨 If you get a 404 error, there might be an issue with the vercel.json settings, so make sure the specified paths are correct.

Deploying the Frontend to Vercel

Proceed with the frontend deployment in the same way as the backend.

Step 1: On the Vercel dashboard, click the "Add New..." button and select "Project."

Step 2: Import the target project.

Step 3: In the project settings, configure the following:

Project Name: Set a name like "my-project".
Framework Preset: Select "Vite" (or "Create React App" if using React only).
Root Directory: Select the frontend directory, such as client.
Environment Variables: Add any necessary variables.
Deploy: Click the "Deploy" button.

Step 4: Verify by accessing the deployed page. If the site is displayed correctly and the connection to the backend is confirmed, you're done! 🎉🎉🎉

Conclusion

That’s it for deploying a full-stack application using Vercel. If things don’t work as expected, double-check your settings and environment variables.

supplement

Reference Video

This video uses MongoDB, so if you're working on a MERN stack project, it might be more relevant.

ℹ️ Note: The video mentions "version": 2 in the vercel.json settings, but the Vercel documentation advises against using the "version" property.

Deployed Project

The project introduced in this article has been deployed and verified using the following tech stack:

Frontend: Vite + React + TypeScript
Backend: Express (Node.js) + TypeScript
Database: Neon (PostgreSQL)
Note: You can use other databases like MongoDB as well.

Repository Structure Example:

├── server             # Backend folder
│   ├── dist           # TypeScript output
│   ├── controllers
│   ├── models
│   ├── routers
│   ├── services
│   └── server.ts
├── client             # Frontend folder
│   ├── src
│   │   ├── components
│   │   ├── utils
│   │   ├── App.tsx
│   │   ├── index.tsx 
│   │   ├── styles
│   │   └── ...
└── package.json

You can check out the actual project here:
Chatbot App
GitHub.

Understanding Environment Variables in Vite: Why VITE_ Prefix is Important

Satomi Nagano / Akikaze1119 — Sun, 01 Sep 2024 22:59:53 +0000

Introduction

When developing a web application with Vite, I encountered an issue where the environment variables I had set up were showing as undefined in the client-side source code.
The following is a summary of the causes and solutions to this problem.

.env.local:

API_KEY=your_api_key

example.tsx:

const API_KEY = import.meta.env.API_KEY;
console.log('API KEY: ', API_KEY);

▽Console

Cause and Solution

The issue was that the environment variables in Vite project required a VITE_ prefix.

▽Before Fix (.env.local:)

API_KEY=your_api_key

↓
▽After Fix (.env.local file:)　←It works😃

VITE_API_KEY=your_api_key

Why is the `VITE_` Prefix Necessary?

So why does Vite require environment variables to have the VITE_ prefix? There are two main reasons:

1. Security

The official documentation explains it as follows:

To prevent environment variables from being accidentally exposed to the client, only variables that start with VITE_ are exposed in the processed code by Vite. For example, in the following environment variables:
.env file:
VITE_SOME_KEY=123
DB_PASSWORD=foobar
Only VITE_SOME_KEY will be exposed to the client source code as import.meta.env.VITE_SOME_KEY, while DB_PASSWORD will not be exposed.
console.log(import.meta.env.VITE_SOME_KEY); // "123"
console.log(import.meta.env.DB_PASSWORD); // undefined

Official documentation link: Environment Variables

Vite strictly manages the environment variables that can be accessed on the client side by default. If all environment variables were exposed to the client side, it could pose a significant security risk. In particular, it’s crucial to prevent sensitive server-side variables, such as API keys or database credentials, from leaking to the client.

Therefore, Vite ensures that only variables with the VITE_ prefix are accessible on the client side, preventing the unintended exposure of sensitive information.

2. Clarity

The VITE_ prefix indicates which environment variables are intended for client-side use. This improves code readability and helps prevent the accidental use of variables that should remain private, particularly in team development environments.

Supplement

1. What Are Environment Variables?

Let's briefly review what environment variables are. Environment variables are variables used to provide configuration values that an application needs to function. By using environment variables, you can easily switch between different environments (e.g., development, testing, production) without modifying your application’s code.

2. Setting Up Environment Variables in Vite

To use environment variables in Vite, you need to create a .env file in the root directory of your project and define your variables there. As mentioned earlier, it’s crucial to prefix your variable names with VITE_.

For example, to set an API key for an external service, your .env file should look like this:

Example:
(.env file)

VITE_API_KEY=your_api_key

(example.tsx)

const apiKey = import.meta.env.VITE_API_KEY;

3. TypeScript Auto-Completion

If you tend to forget details as I do, there’s a way to improve your code's accuracy by using type definitions for import.meta.env. This provides auto-completion in TypeScript.

To set this up, simply create a vite-env.d.ts file in the src directory and define your environment variables within ImportMetaEnv.

Official Documentation: TypeScript Auto-Completion

Conclusion

When setting environment variables in Vite, it’s essential to prefix the variable names with VITE_. This practice not only enhances security but also optimizes your application's performance.

Forem: Satomi Nagano / Akikaze1119

Automatically Send User Data to Database with Clerk OAuth

Key Points

Background

Prerequisites

Implementation Steps

1. Set Up ngrok

1.1 Install and Set Up ngrok

1.2 Obtain an External URL

What is ngrok?

2. Configure Clerk Webhooks

2.1 Access Clerk Dashboard

2.2 Add a Webhook Endpoint

3. Add Signing Secret to .env.local

4. Make the Webhook Route Public

5. Install svix

6. Create the Webhook API Route

7. Test the Webhook

Debugging Tips

User deletion in Clerk

Deploying

Conclusion

Understanding the Difference Between Imperative and Declarative Programming

Comparing Imperative and Declarative Programming with Pizza🍕

Imperative programming analogy:

Declarative programming analogy:

What is Imperative Programming?

What is Declarative Programming?

Conclusion

Reference: Next.js Tutorial

How to Deploy a Full-Stack Application on Vercel

Prerequisites

Deploying the Backend to Vercel

Step 1. Log in to Vercel

Step 2. Add a New Project

How to Adjust GitHub Repository Access Settings

Step 3. Configure the Project

Step 4. Configure vercel.json

Step 5. Confirm Server Access

Deploying the Frontend to Vercel

Conclusion

supplement

Reference Video

Deployed Project

Understanding Environment Variables in Vite: Why VITE_ Prefix is Important

Introduction

Cause and Solution

Why is the VITE_ Prefix Necessary?

1. Security

2. Clarity

Supplement

1. What Are Environment Variables?

2. Setting Up Environment Variables in Vite

3. TypeScript Auto-Completion

Conclusion

3. Add Signing Secret to `.env.local`

5. Install `svix`

Why is the `VITE_` Prefix Necessary?