Forem: Yinka Adedire

Implementing Authorization with Clerk in a tRPC app running on a Cloudflare Worker

Yinka Adedire — Sun, 17 Sep 2023 12:04:55 +0000

While integrating integrating Clerk into a tRPC app on NextJS is documented in the guide Using tRPC and Next.js. I wanted to deploy my tRPC server as a standalone service. So the API could be used for non-browser clients, in my case, a React Native app. I opted to use Cloudflare Workers.

I was able to get the tRPC app up and running, but I ran into some issues with the Clerk integration. I was able to get it working, but I had to do some digging to figure out how to get it working. I figured I'd share what I learned.

Prerequisites

Basic knowledge of tRPC is assumed. If you're not familiar with tRPC, I recommend checking out tRPC docs
A Clerk account. You'll need to create a Clerk app and get your Clerk API key.
A Cloudflare account to deploy the API.

Authorization Strategy

To integrate Clerk into tRPC, we'll use the following authorization strategy:

The user authenticates on the frontend and receives a Clerk session Token.
User sends the session token along with every request to the tRPC API through the Authorization header.
tRPC validates the session token and adds the user data to the tRPC context if the token is valid or null if the token is invalid.
A tRPC auth middleware checks if the user data is in the tRPC context. If it is, the user is authenticated and the request is allowed to continue. If not, the user is not authenticated and the request is rejected.
A protectedProcedure is created which uses the tRPC auth middleware to protect the procedure. If the user is authenticated, the procedure is allowed to continue. If not, the procedure is rejected.

Set up tRPC

After your project is initialized, you'll need to install the tRPC server package and zod for validation. Navigate to your project directory and run the following command:

Install tRPC

npm install @trpc/server zod

Next, create a trpc.ts file in the src directory. This is where we'll set up our tRPC server and context. Add the following code to the file:

import { initTRPC, inferAsyncReturnType } from "@trpc/server";
import { FetchCreateContextFnOptions } from "@trpc/server/adapters/fetch";

// context holds data that all of your tRPC procedures will have access to
export const createContext = async (options: FetchCreateContextFnOptions) => {
  return {};
};

// initialize tRPC
const t = initTRPC.context<typeof createContext>().create();

export const router = t.router;
export const publicProcedure = t.procedure;

Create a tRPC router

Next, create a router.ts file in the src directory. This is where we'll define our tRPC routers. Add the following code to the file:

import { z } from "zod";
import { router, publicProcedure } from "./trpc";

// example router
export const exampleRouter = router({
  sayHello: publicProcedure
    .input(
      z.object({
        name: z.string(),
      })
    )
    .query(({ input }) => {
      return {
        greeting: `Hello ${input.name}`,
      };
    }),
});

// app router
export const appRouter = router({
  example: exampleRouter,
});

export type AppRouter = typeof appRouter;

Create a Cloudflare Worker project

You can initialize a new Cloudflare Worker project by running the npm create cloudflare@2 -- <project-name> command in your terminal and answering the prompts that follow. I named my project trpc-clerk-cloudflare-worker. Choose the hello-world template when prompted. In my case, I also chose to use TypeScript.

npm create cloudflare@2 -- trpc-clerk-cloudflare-worker

Startup the tRPC server with Cloudflare Worker

Next, navigate to the entry point of your project, which is located at src/index.ts by default. Add the following code to the file:

import { appRouter } from "./router";
import { createContext } from "./trpc";
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";

export default {
  async fetch(request: Request): Promise<Response> {
    const response = await fetchRequestHandler({
      req: request,
      createContext,
      endpoint: "/trpc",
      router: appRouter,
      onError({ error, path }) {
        console.error(`tRPC Error on '${path}'`, error);
      },
    });

    return response;
  },
};

Handle CORS and CORS preflight requests

Lastly, we need to handle CORS and CORS preflight requests. Add the following code to the src/index.ts file:

import { appRouter } from "./router";
import { createContext } from "./trpc";
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";

export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method === "OPTIONS") {
      return handleCORSPreflight();
    }

    const response = await fetchRequestHandler({
      req: request,
      createContext,
      endpoint: "/trpc",
      router: appRouter,
      onError({ error, path }) {
        console.error(`tRPC Error on '${path}'`, error);
      },
    });

    return addCORSHeaders(response);
  },
};

const addCORSHeaders = (res: Response) => {
  const response = new Response(res.body, res);
  response.headers.set("Access-Control-Allow-Origin", "*");
  response.headers.set("Access-Control-Allow-Headers", "*");
  response.headers.set("Access-Control-Allow-Credentials", "true");
  response.headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");

  return response;
};

const handleCORSPreflight = () => {
  return new Response(null, {
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Headers": "*",
      "Access-Control-Allow-Credentials": "true",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
    },
  });
};

To test that everything is working, run npm run start in your terminal. If everything goes well, you should see an output similar to this:

$ wrangler dev
⛅️ wrangler 3.8.0
------------------

.....

⎔ Starting local server...
[mf:inf] Ready on http://0.0.0.0:xxxxx

You can now test your tRPC server by making a request to http://localhost:xxxxx/trpc. You should see a response similar to this:

{
  "error": {
    "message": "No "query"-procedure on path",
    "code": -32004,
    "data": {
      "code": "NOT_FOUND",
      "httpStatus": 404,
      "stack": "...blah...blah",
      "path": ""
    }
  }
}

Integrate Clerk with tRPC

Install Clerk Backend SDK

Next, install the Clerk backend SDK package by running the following command in your terminal:

npm install @clerk/backend

Set environment secrets

Go to your Clerk dashboard and create a new Clerk app. Once your app is created, you'll need to get your Clerk API key. We'll utilize Cloudflare Workers Secrets to securely store our Clerk API key. To do this, create a .dev.vars file in the root of your project and add the API key to the file like this:

CLERK_API_KEY=<your-clerk-api-key>

Go to your Cloudflare worker entry point, src/index.ts, and modify the fetch function to look like this:

// ...imports

export interface Env {
  CLERK_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method === "OPTIONS") {
      return handleCORSPreflight();
    }

    const headers = new Headers();

    const response = await fetchRequestHandler({
      req: request,
      //   env is passed to the createContext function
      createContext: () =>
        createContext({ env: env, req: request, resHeaders: headers }),
      endpoint: "/trpc",
      router: appRouter,
      onError({ error, path }) {
        console.error(`tRPC Error on '${path}'`, error);
      },
    });

    return addCORSHeaders(response);
  },
};

// ...rest of the code

Using Clerk in your tRPC Context

Navigate to trpc.ts where we created a createContext function earlier. We'll need to update the createContext function to use the Clerk backend SDK to validate the session token and add the user session data to the tRPC context. We also need to modify the createContext function to accept an env parameter. Add the following code to the trpc.ts file:

// import the Env interface
import { Env } from ".";
import { Clerk } from "@clerk/backend";
import { initTRPC, inferAsyncReturnType, TRPCError } from "@trpc/server";
import { FetchCreateContextFnOptions } from "@trpc/server/adapters/fetch";

// update the createContext function to accept an env parameter
interface Context extends FetchCreateContextFnOptions {
  env: Env;
}

// context holds data that all of your tRPC procedures will have access to
export const createContext = async ({ req, env }: Context) => {
  const clerk = Clerk({ apiKey: env.CLERK_API_KEY });
  const userId = req.headers.get("authorization");

  //If there is no session token, return null
  if (!userId) return { session: null };

  // otherwise, get the session
  const user = await clerk.users.getUser(userId);
  return {
    user,
  };
};

// ...rest of the code

Create a tRPC auth middleware

The next step is to create a tRPC auth middleware. This middleware will check if the user session data is in the tRPC context. We'll also create a protectedProcedure which uses the tRPC auth middleware. We can then use the protectedProcedure to protect any procedure we want to require authentication. Add the following code to the trpc.ts file:

// ... rest of the code

const isAuthenticated = t.middleware(({ ctx, next }) => {
  if (!ctx.user?.id) throw new TRPCError({ code: "UNAUTHORIZED" });

  return next({
    ctx: {
      user: ctx.user,
    },
  });
});

export const protectedProcedure = t.procedure.use(isAuthenticated);

Create a route that requires authentication

Now that we have our auth middleware, we can create a route that requires authentication. Add the following code to the router.ts file:

// Example protected procedure
export const exampleProtectedRouter = router({
  // this is accessible only if the user is authenticated
  getSecret: protectedProcedure.query(({ ctx }) => {
    return {
      secret: `User ID: ${ctx.user.id}`,
    };
  }),
});

export const appRouter = router({
  example: exampleRouter,
  // add new router to app router
  protectedExample: exampleProtectedRouter,
});

Deploy your tRPC API

The next step is to deploy your tRPC API. Before we do that, we need to add our Clerk API key to our Cloudflare Worker environment. To do this, run npx wrangler secret put CLERK_API_KEY in your terminal, you'll be prompted to enter your Clerk API key. Once you've added your Clerk API key, you can deploy your tRPC API by running npm run deploy in your terminal. If everything goes well, you should see an output similar to this:

> trpc-clerk-cloudflare-worker@0.0.0 deploy
> wrangler deploy

 ⛅️ wrangler 3.8.0
------------------
Total Upload: 257.98 KiB / gzip: 50.85 KiB
Uploaded trpc-clerk-cloudflare-worker (2.75 sec)
Published trpc-clerk-cloudflare-worker (3.32 sec)
https://trpc-clerk-cloudflare-worker.xxx.workers.dev
Current Deployment ID: xxxx-8443-xxx-b0a6-37xxxx0d4b5f13

Testing everything out

To make sure everything works as expected, we'll create a simple tRPC NextJS frontend app that uses the tRPC API we just created. We'll use the Clerk's Next.js SDK to authenticate the user and get the session token. We'll then use the session token to make a request to the tRPC API.

Since one of the main advantages of tRPC is to share types between the frontend and backend, we'll create a parent folder that will hold both the frontend and backend code. We'll call this folder trpc-clerk.

Create a NextJS app

Create a new NextJS app by running npx create-next-app@latest in your terminal and answering the prompts that follow. I named my app trpc-clerk-nextjs and also chose to use the App router.

Our folder structure should now look like this:

trpc-clerk
│
├── trpc-clerk-nextjs
│
└── trpc-clerk-cloudflare-worker

Set Up Clerk In Your NextJS App

Follow Clerk's NextJS Guide to set up Clerk in your NextJS app. Once you've completed the guide, you should have a working NextJS app with Clerk authentication.

Setup tRPC in your NextJS app

You'll need to install the tRPC client package and its dependencies. Navigate to your NextJS app directory and run the following command:

npm install @trpc/client @trpc/server @trpc/react-query @tanstack/react-query @tanstack/react-query-devtools @tanstack/react-query-next-experimental zod

Create tRPC hooks

Next, we need to create our strongly-typed React hooks using the createTRPCReact function from @trpc/react-query and our AppRouter type definition from our tRPC API. Create a trpc.ts file in the app directory of our NextJS app and add the following code to the file:

import { createTRPCReact } from "@trpc/react-query";
// import our AppRouter type definition
import type { AppRouter } from "../../trpc-clerk-cloudflare-worker/src/router";

export const trpc = createTRPCReact<AppRouter>();

Setup tRPC Provider

First, we add the URL of your tRPC API to your .env.local file: NEXT_PUBLIC_API_URL=<your-trpc-api-url>. Next, we need to create a tRPC client and wrap our NextJS app in a tRPC provider. To do that, create a provider.tsxfile in theapp directory of our NextJS app and add the following code to the file:

"use client";
import React from "react";
import { trpc } from "./trpc";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
import { loggerLink, unstable_httpBatchStreamLink } from "@trpc/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryStreamedHydration } from "@tanstack/react-query-next-experimental";

interface Props {
  headers: Headers;
  userId: string | null;
  children: React.ReactNode;
}

const API_URL = const API_URL = process.env.NEXT_PUBLIC_API_URL;

export const AppProvider: React.FC<Props> = (props) => {
  const [queryClient] = React.useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 5 * 1000,
          },
        },
      })
  );

  const [trpcClient] = React.useState(() =>
    trpc.createClient({
      links: [
        loggerLink({
          enabled: (opts) =>
            process.env.NODE_ENV === "development" ||
            (opts.direction === "down" && opts.result instanceof Error),
        }),
        unstable_httpBatchStreamLink({
          url: `${API_URL}/trpc`,
          headers() {
            const headers = new Map(props.headers);
            // ypu can set any http headers you want here
            headers.set("x-trpc-source", "nextjs");
            headers.set("authorization", `${props.userId}`);
            return Object.fromEntries(headers);
          },
        }),
      ],
    })
  );

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        <ReactQueryStreamedHydration>
          {props.children}
        </ReactQueryStreamedHydration>
        <ReactQueryDevtools initialIsOpen={false} />
      </QueryClientProvider>
    </trpc.Provider>
  );
};

Wrap your NextJS app in the tRPC provider

Now that we have our tRPC provider, we need to wrap our NextJS app in the provider, pass in the userId and headers props, and pass the props to the AppProvider component. To do this, open the layout.tsx file in the app directory of our NextJS app and add the following code to the file:

import "@/app/globals.css";
import { headers } from "next/headers";
import { AppProvider } from "@/app/provider";
import { ClerkProvider, auth } from "@clerk/nextjs";

interface Props {
  children: React.ReactNode;
}

export default async function RootLayout({ children }: Props) {
  const { userId } = auth();

  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <AppProvider headers={headers()} userId={userId}>
            {children}
          </AppProvider>
        </body>
      </html>
    </ClerkProvider>
  );
}

Make a request to your tRPC API

Finally! We're ready to make a request to our tRPC API. To do this, open the page.tsx file in the app directory of our NextJS app and add the following code to the file:

"use client";
import { trpc } from "./trpc";
import { UserButton } from "@clerk/nextjs";

export default function Home() {
  const greet = trpc.example.sayHello.useQuery(
    {
      name: "John Doe",
    },
    {
      enabled: false,
    }
  );

  const getProtectedSecret = trpc.protectedExample.getSecret.useQuery(
    undefined,
    {
      enabled: false,
    }
  );

  return (
    <div>
      <UserButton afterSignOutUrl="/" />

      <div>
        <div>
          <div>
            {getProtectedSecret.data
              ? getProtectedSecret.data?.secret
              : "************"}
          </div>
          <button onClick={() => getProtectedSecret.refetch()}>
            {getProtectedSecret.isFetching ? "Loading..." : "Get Secret"}
          </button>
        </div>

        <div>
          <div>{greet.data ? greet.data?.greeting : "************"}</div>
          <button onClick={() => greet.refetch()}>
            {greet.isFetching ? "Loading..." : "Say Hello"}
          </button>
        </div>
      </div>
    </div>
  );
}

Wrapping up

That's it! You should now have a working tRPC API that uses Clerk for authentication. You can find the complete code for this tutorial here

Resources

How to make Radix UI Tabs URL based in NextJS

Yinka Adedire — Tue, 18 Jul 2023 09:15:13 +0000

Tab is a common user interface pattern where contents are separated into different panes, each of which is viewable one at a time, allowing users to switch between different sections without changing the page.

Radix UI is a primitive, unstyled, customizable and accessibility focused React component library that provides a foundation for developers to build accessible components upon.

In this tutorial, you'll learn how to make Radix UI tabs URL based in NextJS without causing a full page reload. We'll start with setting up a new project, create a basic Radix UI tabs component, and finally make it URL based by integrating it with NextJS router.

Requirements

Basic understanding of JavaScript and React
Node.js and NPM installed on your machine
A text editor like VS Code

Making Tabs URL-based significantly makes your web application more accessible and user-friendly. It gives users and developers the ability to directly link to a specific content within the app, makes the URL bookmarkable and allows users to share specific content state by simply sharing a URL. It also maintains the user's navigation state if they accidentally reloaded the page, they would conveniently get back to their last active tab.

An example URL could look like this:

https://app.com/page?tab=specificTab

Step 1: Setting Up the Project

To bootstrap a Next.js project, we'll use the official create-next-app CLI by running the following commands:

npx create-next-app@latest

When you run the command, it initiates an interactive session where you have to provide specific details like project name. Once you answer all the prompts, a new Next.js application will be created for you.

Navigate to the newly created project folder and open it with a text editor like VS Code.

Step 2: Creating a Basic Radix UI Tabs Component

The next step is to create a basic Radix UI tabs component. We'll use the Tabs component from @radix-ui/react-tabs package.
Install the package by running the following command:

# with npm
npm install @radix-ui/react-tabs

# with yarn
yarn add @radix-ui/react-tabs

The Tabs component is the parent component that wraps all the other components. It accepts a defaultValue prop that sets the default active tab. The TabList component is a wrapper for all the TabTrigger components. The TabTrigger component is a clickable element that triggers the tab change. The TabContent component is a wrapper for the tab content.

Next, create a Tabs component in pages/index.tsx file:

import * as Tabs from "@radix-ui/react-tabs";

const TabsDemo = () => {
  return (
    <Tabs.Root>
      <Tabs.List>
        <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
        <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
        <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
      </Tabs.List>

      <Tabs.Content value="tab1">Tab 1 content</Tabs.Content>
      <Tabs.Content value="tab2">Tab 2 content</Tabs.Content>
      <Tabs.Content value="tab3">Tab 3 content</Tabs.Content>
    </Tabs.Root>
  );
};

export default function Home() {
  return <TabsDemo />;
}

Step 3: Integrating with NextJS Router

The first step to make Radix UI tabs URL based is to make it's state controlled by using React's useState hook to create a state variable that holds the active tab value. We'll then pass the state variable to the Tabs component as a value prop then create a function that handles the tab change and pass it to the Tabs component as an onValueChange prop.

import React from "react";
import * as Tabs from "@radix-ui/react-tabs";

const TabsDemo = () => {
  const [activeTab, setActiveTab] = React.useState("tab1");

  const handleTabChange = (value) => {
    setActiveTab(value);
  };

  return (
    <Tabs.Root
      value={activeTab}
      defaultValue="tab1"
      onValueChange={handleTabChange}
    >
      <Tabs.List>
        <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
        <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
        <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
      </Tabs.List>

      <Tabs.Content value="tab1">Tab 1 content</Tabs.Content>
      <Tabs.Content value="tab2">Tab 2 content</Tabs.Content>
      <Tabs.Content value="tab3">Tab 3 content</Tabs.Content>
    </Tabs.Root>
  );
};

Finally, we'll integrate the Tabs component with NextJS router by using the useRouter hook to get the current tab value from the URL query parameter and set it as the initial tab value. We'll also add a useEffect hook that listens to the router query parameter changes and updates the active tab value accordingly.

Here is the final code:

import React from "react";
import { useRouter } from "next/router";
import * as Tabs from "@radix-ui/react-tabs";

const TabsDemo = () => {
  const router = useRouter();
  const initialTab = router.query.tab;
  const [activeTab, setActiveTab] = React.useState(initialTab || "tab1");

  const handleTabChange = (value) => {
    //update the state
    setActiveTab(value);
    // update the URL query parameter
    router.push({ query: { tab: value } });
  };

  // if the query parameter changes, update the state
  React.useEffect(() => {
    setActiveTab(router.query.tab);
  }, [router.query.tab]);

  return (
    <Tabs.Root
      value={activeTab}
      defaultValue="tab1"
      onValueChange={handleTabChange}
    >
      <Tabs.List>
        <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
        <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
        <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
      </Tabs.List>

      <Tabs.Content value="tab1">Tab 1 content</Tabs.Content>
      <Tabs.Content value="tab2">Tab 2 content</Tabs.Content>
      <Tabs.Content value="tab3">Tab 3 content</Tabs.Content>
    </Tabs.Root>
  );
};

Conclusion

In this tutorial, you learned how to make Radix UI tabs URL based in NextJS without causing a full page reload. You can find the full source code on GitHub and the live demo here.

Resources

How to set up an AWS S3 bucket for Medusa S3 file plugin.

Yinka Adedire — Tue, 18 Oct 2022 05:00:15 +0000

Medusa requires a file storage plugin to host your store's files like product images. In this tutorial, we'll learn to use AWS S3 as our storage provider by using the medusa-file-s3 plugin.

Prerequisites

To follow along with this tutorial, you need to set up a Medusa server. You can easily set one up by following this quickstart guide from the Medusa docs.

Create an AWS account if you don't already have one.

Create an AWS IAM User and Group

It's a best practice to not use the AWS account root user for any task where it's not required for security reasons.

We need to create an IAM user and user group with AmazonS3FullAccess permission. Follow the steps here to create an IAM admin user and group.

Create new user

Give it Programmatic access and AWS Management Console access, then set a custom password and for simplicity, unselect the required user to create a new password at the next sign-in option. For this tutorial, I named the new user medusa-server-admin.

Create user group

We need to create a user group associated with our newly created user in order to give it permission. Create a new user group and give it AmazonS3FullAccess permission.
For this tutorial, I named the new user group medusa-server-admins

Click Next:Tags > Next:Review > Create User.

Add the newly generated Access key ID and Secret access key to the .env file in the root folder of your Medusa server. For this tutorial, I named the .env keys S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY respectively.

Login as IAM User

To log in to the newly created IAM user, you will need the Account ID of the root user, in addition to the IAM username and password you created earlier. You can get the root user account ID easily by clicking on the username in the top right corner of the AWS console, the account ID will be displayed in the Account ID field.

Sign out of your root AWS account and sign in to the IAM user you just created.

Create S3 Bucket

Go to the AWS S3 console, click on Create bucket

Enter a name for your bucket and select a region. N Virginia and Ohio are typically the cheapest regions. For this guide, I named my bucket medusa-starter-monster-s3 and selected N Virginia as the region.

In the Object Ownership section, select ACLs enabled to enable access to the bucket from your medusa server, then select Bucket owner preferred.

In the Block Public Access section, uncheck the Block all public access checkbox. This will show a warning and a checkbox to confirm your action, check the checkbox.

Scroll to the bottom of the page and click Create bucket.

On the newly created bucket page, click on Permissions and then Bucket Policy. We need to write a policy that allows public read access to the bucket.

You can use the AWS Policy Generator to generate a policy for your bucket. For simplicity, click the Edit button and paste the following policy in the bucket policy field. Replace YOUR_BUCKET_NAME with the name of your bucket. Click Save changes to save the policy.

Add an S3_BUCKET_NAME, S3_BUCKET_REGION, and S3_BUCKET_URL key in the .env file and fill in the values with your bucket name and region and S3 bucket URL. The S3 bucket URL is in the format<https://<YOUR_BUCKET_NAME>.s3>.<REGION>.amazonaws.com. For this tutorial, my S3 bucket URL is<https://medusa-starter-monster-s3.s3.us-east-1.amazonaws.com>.

Install `medusa-file-s3`

We need to install medusa-file-s3 package in our Medusa server. Navigate to the root of the medusa server and install it.

# using npm
npm install medusa-file-s3

# using yarn
yarn add medusa-file-s3

Finally, add the plugin configs to medusa-config.js file.

const plugins = [
  // other plugins
  {
    resolve: `medusa-file-s3`,
    options: {
      s3_url: process.env.S3_BUCKET_URL,
      bucket: process.env.S3_BUCKET_NAME,
      region: process.env.S3_BUCKET_REGION,
      access_key_id: Sprocess.env.S3_ACCESS_KEY_ID,
      secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
    },
  },
];

module.exports = {
  projectConfig: {
    // project configs
  },
  plugins,
};

Test It Out

Start the medusa server using npm run start or yarn start.

Set up the Medusa Admin if you haven't already. You can follow the quickstart guide to set it up. In the Medusa Admin, add a new product and upload an image for it. If everything is set up correctly, the product image will be uploaded to your S3 bucket successfully.

How to Setup A Medusa Server Locally

Yinka Adedire — Sat, 08 Oct 2022 04:46:57 +0000

Medusa is a NodeJS-based headless e-commerce platform marketed as an open-source and viable alternative to Shopify.

At the end of this article, you should know what Medusa is, install and setup Medusa. This tutorial requires basic knowledge of NodeJS, NPM, and Git.

A Primer On Medusa

A Medusa store comprises three components: A headless server, an admin dashboard, and a storefront.

The Medusa headless server is the component that holds the store’s core functionalities and data. The Admin dashboard and Storefront interact with the headless server via the Admin REST APIs and Storefront REST APIs. The headless server consists of NodeJS and Postgres for the database.

The Admin dashboard is the UI part of the store accessible by the store operators. Store operators can use the admin dashboard to create, view, and edit product data and orders.

The Storefront is the UI part of the store that customers see and interact with to view products and make orders. The Storefront is typically built using client-side Javascript Frameworks like React (NextJS, Gatsby) and VueJS.

Requirements

Install NodeJS

Medusa is built on NodeJS so it is required to run. NodeJS - Medusa currently supports Node versions 14 and 16. You can check which version you have by running node -v in the terminal. If you don’t already have Node installed on your computer, read this article on how to install NodeJS.

Install the Medusa CLI

Install the Medusa CLI globally using NPM



npm install @medusajs/medusa-cli --global

Create a Medusa Server Project

Bootstrap a new Medusa server project and seed with sample product data. For this tutorial, we’re going to create a Medusa e-commerce store for Watches, let’s name it watch-store-medusa-server.



medusa new watch-store-medusa-server --seed

Start the Medusa Server

Navigate to our medusa server project directory and start the server



cd watch-store-medusa-server
medusa develop

Test It Out

Send a get request to the API’s products endpoint using curl in a different terminal window to confirm the server is running properly.



curl localhost:9000/store/products

# If you have Python installed, you can format the JSON result.
curl localhost:9000/store/products | python -m json.tool

Medusa Server Configuration

Open the medusa project folder in a code editor like VS Code, At the root of the folder, there's a medusa-config.js file, the file contains all the configurations for your Medusa server like database and plugin. It's important to configure your Medusa server properly.

Install PostgreSQL

PostgreSQL is an open-source relational database system. Although Postgres isn't required to run a Medusa server, it is highly recommended as it gives you a more production-like environment. If you don’t already have Postgres installed, these tutorials explain how to install PostgreSQL on Windows, Linux and macOS

To check if the installation was successful or if you already have Postgres installed, run:



psql -V

Create Postgres Database

Before getting started with configuring PostgreSQL, we have to create a database.



access the postgres console
psql postgres

# create a new user
CREATE USER medusa_admin WITH PASSWORD 'medusa_admin_password';

# create a new database and the newly created user as the owner
CREATE DATABASE medusa_db OWNER medusa_admin;

# grant all privileges on medusa_db to the medusa_admin user
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_admin;

# exit the postgres console
quit

Add the Postgres URL to the environmental variable

Using this Postgres database URL template : postgres://<username>:<password>@<host>:<port>/<database> and default port 5432. Add the following line to the .env file at the root of our medusa server folder:




DATABASE_URL=postgres://medusa_admin:medusa_admin_password@localhost:5432/medusa_db

Configure Postgres in `medusa-config.js`



module.exports = {
  projectConfig: {
        //...other configurations
    database_url: process.env.DATABASE_URL,
    database_type: "postgres",
  },
};

You can go on to delete the default SQLite database file and it's reference in medusa-config.js

Install Redis

Redis is an open-source in-memory data structure store. It can be used for distributing and emitting messages and caching, among other purposes.

Although Redis is not required for the Medusa Server to run, you need to install Redis if you want to use subscribers to handle events such as when an order is placed and perform actions based on them. This tutorial explains how to install Redis on your computer.

To confirm the installation was successful or if you already have Redis installed, run:



redis-server -v

Start Redis Server

Learn how to start and stop a Redis server with this tutorial



# start redis server on mac
brew services start redis

# start redis server on linux
sudo systemctl enable redis

Add Redis the Server URL to the environmental variable

The default Redis URL on local host is redis://localhost:6379



REDIS_URL=redis://localhost:6379

Configure Redis in medusa-config.js



module.exports = {
  projectConfig: {
    //...other configurations
    redis_url: process.env.REDIS_URL
  },
};

Test It Out

Restart the medusa server to check if everything is running fine.



# seed new postgres database
npm run seed 

# start the server
npm run start

Setup A File Storage Plugin

In order to manage file storage in Medusa (e.g for uploading product images), you need to integrate a file storage plugin. Medusa provides three options to handle your file storage: MinIO, Amazon S3 and DigitalOcean Spaces.

Set up MinIO

It is recommended to use MinIO for local development. MinIO is similar to Amazon S3, except that it is self-hosted. You can install MinIO on your computer by following this tutorial.

Launch MinIO Server

Always make sure that your MinIO server is running when your Medusa server is running.

MinIO has a default address port of 9000, which clashes with Medusa, which also uses port 9000. You should change MinIO’s port from 9000 to something else e.g 9001.



# launch the minio server on port 9001
minio server ~/data --address ":9001"

Once the Minio server is running, you can access the console from the browser with the URL and credentials the MinIO server prints to the terminal.

Create a MinIO bucket

A bucket is similar to a folder or directory in a filesystem, where each bucket can hold an arbitrary number of objects.

You should see a page similar to the one shown in the screenshot after logging into the MinIO console. Click on the “Create Bucket” button to create a new bucket to store your Medusa server files. You can name the bucket whatever you like, for this tutorial, I’ll name the bucket “medusa”.

After creating the bucket, you need to set its access policy to Public.

Click the “Buckets” button on the sidebar, then the “Manage” button.

Click on the Access Policy button and set it to public.

You also need to generate Access keys.

Click on “Identity > Service Accounts” in the sidebar of the console, then click on the “Create service account” button.

A random Access Key and Secret Key will be generated. Once you click the Create button, a modal showing the Secret Key will be displayed. Make sure to copy it down somewhere safe before you close the modal, as it will only display once.

Install Medusa MinIO Plugin

Navigate to the medusa server project directory and install the plugin.



npm install medusa-file-minio

Open the medusa server in a code editor like VScode and add the following to the .env file:



MINIO_ENDPOINT=<ENDPOINT>  # URL of your MinIO server
MINIO_BUCKET=<BUCKET> # MinIO Bucket Name
MINIO_ACCESS_KEY=<ACCESS_KEY> # MinIO Bucket access key generated earlier.
MINIO_SECRET_KEY=<SECRET_KEY> # MinIO Bucket secret key generated earlier.

The final values should look similar to this:



MINIO_ENDPOINT=http://127.0.0.1:9001
MINIO_BUCKET=medusa
MINIO_ACCESS_KEY=p1Vuc3Ojxxxxxx
MINIO_SECRET_KEY=fSpy9aHSMywNhRKdxxxxxxxx

Finally, add the configuration to the medusa-config.js file.



const plugins = [
  // other plugins
  {
    resolve: `medusa-file-minio`,
    options: {
      bucket: process.env.MINIO_BUCKET,
      endpoint: process.env.MINIO_ENDPOINT,
      access_key_id: process.env.MINIO_ACCESS_KEY,
      secret_access_key: process.env.MINIO_SECRET_KEY,
    },
  },
];

module.exports = {
  projectConfig: {
   // other configs
  },
  plugins,
};

If you intend to use NextJS for your storefront, you will need to add the MinIO domain name into the configured images domain names in your NextJS project next.config.js file, so as to not receive the next/image Un-configured Host error.



module.exports = {
  images: {
    domains: [
      "127.0.0.1",
      // other domains
    ],
  },
};

Test it Out

Check if everything is running fine. Don’t forget to always make sure that your MinIO server is running when your Medusa server is running.



# launch the minio server on port 9001
minio server ~/data --address ":9001"


# start the medusa server on a new terminal tab
npm run start

Congratulations! you have successfully set up a medusa server. There are still other things you can configure like JWT and Cookie Secrets, CORS and Plugins. For additional information, check out the official docs about Server Configurations. You can also read about how to set up a Medusa Admin or read about the Storefront REST API to create Storefronts.

How To Integrate Gatsby with Shopify using Shopify Custom Apps

Yinka Adedire — Tue, 31 May 2022 09:08:41 +0000

This tutorial provides the steps to integrate Gatsby.js with a Shopify store. It assumes a basic knowledge of Gatsby.js.

By the end of this tutorial, you'll have a Gatsby site that you can query and see your Shopify store data in the GraphiQL explorer.

The steps include:

Create a Shopify account, preferably, a Shopify partners account. (If you don't have one already)
Create a Shopify store and add some products.
Setup a Gatsby.js project.
Create and install a Shopify custom app on your Shopify store.
Install the Gatsby.js plugin and its peer dependencies to query products from Shopify.
Setup the Gatsby.js Shopify source plugin with details from the Shopify custom app created earlier.

Create A Shopify Account

You need to create a Shopify account before you can set up a store on Shopify.

All Shopify's plans aren't free, but Shopify provides a free development-purpose only store. The only restriction is you can't accept actual payments without upgrading first. You need to create a Shopify Partners account to create the development-only store. You can skip this step if you already have an active Shopify store.

Setup A Shopify Store.

Now that you have a Shopify account, the next step is to create a Shopify Store.

Click on "Add Store".
Pick a store type of Development Store.
Enter Your store details.
Wait for Shopify to create your store.
Add some products.

Setup Shopify Custom app

To create a custom app, navigate to the "Apps" section of your Shopify store admin.

Then click the "Develop apps for your store" button

Allow custom apps development when prompted.
Click on the "Create an app" button.
Enter the app name, you can name it whatever you like, "Gatsby Storefront" - for example.

Configure Admin API Scopes

The next step is to configure access scopes for the custom app.

Navigate to your Custom App Overview Page (if you aren't redirected there already)

Click on the "Configure Admin API Scopes" button
Allow Read access for Files and Products.
You can also allow Read access for:
- Product listings if you will enable Gatsby to source collections data in the plugin options. (We'll allow that for this tutorial)
- Orders if you will enable Gatsby to source orders data in the plugin options.
- Inventory and Locations if you will enable Gatsby to source locations data in the plugin options.
Click on the Save button.

Configure Storefront API Scopes

If you are planning on managing your cart within Gatsby you will also need to configure storefront API access scopes.

Navigate back to your Custom App Overview Page, then go to the "Configuration" tab

Click on the "Configure" button of the Storefront API integration card.
Allow Read and modify checkouts
Click on the "Save" button

Install the App

Navigate back to your Custom App Overview page, then click on the "Install app" button.

Setup Gatsby.js site

If you don't already have a Gatsby codebase, you can initialize a new Gatsby project using npm, then follow the prompt to suit your preferred choice.

npm init gatsby

You can also use a starter like [gatsby-starter-ts](https://github.com/jpedroschmitz/gatsby-starter-ts)

Store API Credentials from Shopify

Create a .env file at the root of your Gatsby project.
Navigate back to your Custom App Overview page on Shopify, then go to the "API Credentials" tab
Store the the Admin API access token in the .env file as SHOPIFY_ADMIN_API_ACCESS_TOKEN=your-admin-api-access-token. Be careful as you can only reveal it once.
Store the Storefront API access token in the .env file as GATSBY_STOREFRONT_ACCESS_TOKEN=your-storefront-access-token
Also store your Shopify store URL in the .env file as GATSBY_SHOPIFY_STORE_URL=your-url.myshopify.com

Your .env file should now look like the code block below:

SHOPIFY_ADMIN_API_ACCESS_TOKEN=shpat_XXX
GATSBY_STOREFRONT_ACCESS_TOKEN=XXX
GATSBY_SHOPIFY_STORE_URL=your-url.myshopify.com

Install and setup plugin

Install gatsby-source-shopify which is the Gatsby plugin used to source data from Shopify. and it's required peer dependency, gatsby-plugin-image. gatsby-plugin-image also has peer dependencies of gatsby-plugin-sharp and gatsby-transformer-sharp.

npm install gatsby-source-shopify gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

Configure the plugins in the gatsby-config.js file of your Gatsby project.

require("dotenv").config()

plugins: [
    "gatsby-plugin-image",
    "gatsby-plugin-sharp",
    "gatsby-transformer-sharp",
    {
      resolve: "gatsby-source-shopify",
      options: {
        storeUrl: process.env.GATSBY_SHOPIFY_STORE_URL,
        password: process.env.SHOPIFY_ADMIN_API_ACCESS_TOKEN,
        shopifyConnections: ["collections"], // source product collections too
      },
    },
  ],

Note:
The gatsby-source-shopify doc has a guide on how to configure but with Shopify private apps which is now deprecated since January 2022.

Fire it up

Run your site with npm run develop. When the site builds, you should see be able to see your Shopify store data in the GraphiQL explorer at http://localhost:8000/___graphql

Thank you and congratulations if you made it this far. 🥳

Resources

Gatsby Source Shopify Plugin
Shopify Private apps deprecated

How to create and deploy a Strapi project on Railway

Yinka Adedire — Fri, 08 Apr 2022 14:51:31 +0000

Railway is a cloud platform based on Heroku that makes it easy to deploy you app on the cloud. You can provision infrastructure, develop with the infrastructure locally, and deploy your app easily.

Strapi is a NodeJS based open-source CMS that's highly customizable and self-hosted.

In this tutorial, you'll learn to create a demo Strapi project and deploy it on Railway for free. You'll also pick up a few tricks along the way.

This tutorial assumes you have a basic familiarity with NPM, Git & Github, and Strapi.

Creating A Strapi Project

Create a new strapi project with the following installation script:



# using npm 
npx create-strapi-app@latest demo-strapi-project
# using yarn
yarn create strapi-app demo-strapi-project

Now we should have a demo-strapi-project folder. You can start the development server using:



npm run develop # with npm
 
yarn develop # with yarn

If everything goes well, you should see a login screen like this:

You can go on to create content-types with Strapi content type builder, and add contents to the new Strapi project.

Deploying on Railway

Strapi comes with an SQLite database by default, which is good for local development but not for production.

So, for the production deployment, you'll use PostgreSQL provisioned on Railway.

Create a Railway account, if you haven't already.
Create a new project on Railway. Go to Dashboard > New project, you should see a screen similar to the image below:

Create a new Postgres database by clicking on the 'Provision PostgreSQL' option. Clicking on our created PostgreSQL service and clicking on the Variables tab should show a screen similar to the image below:

Get the environment variables for the production deployment

Create a .env.production file in the root folder of our Strapi project.

Copy & Paste the environment variables from the PostgreSQL database we created on Railway earlier.

Paste the environment variables from .env that came by default at the root folder of your Strapi project over to our newly created .env.production file.

Add a NODE_ENV=production entry to the .env.production file, (to let Strapi know it's a production build)

The .env.production file should look similar to the code block below:



NODE_ENV=production
HOST=0.0.0.0 PORT=1337
APP_KEYS=1TQ+R52DVEXXXXXX==,eurEB0npfVqxWRi+XXXXX
JWT_SECRET=41115xxxxxxxxxxx56229945eda
API_TOKEN_SALT=05f84xxxxxxxxxxx0f99b3ea1
PGPASSWORD=1JxxxxxxxxxxxUBHwD PGHOST=containerxxxxxxx.railway.app
PGPORT=5931
PGUSER=postgres
PGDATABASE=railway

The next step is to configure Strapi to use the PostgreSQL database we created earlier on Railway.

Since we'll be using a PostgreSQL database, install node-postgres, a PostgreSQL client for NodeJS, using:



npm install # npm

yarn add pg # yarn

The default database connection configuration file path is ./config/database.js. But we want to keep the default SQLite database for local development and the remote PostgreSQL database for production. (for reasons like speed, avoid reaching your Railway free tier limit).

Strapi has a feature that lets you set different configurations for specific environments using ./config/env/{environment}/{config-filename.js} naming and structure convention.

To do this:
- Create an env folder in the config folder at the root of your Strapi project folder.
- Create a production folder in our created env folder (Because you're configuring for the production environment).
- Create a database.js file in the new production folder (Since we're defining a database configuration) i.e ./config/env/production/database.js
The content of your new database.js file should look similar to the code block below:



module.exports = ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      host: env('PGHOST', '127.0.0.1'),
      port: env.int('PGPORT', 5931),
      database: env('PGDATABASE', 'railway'),
      user: env('PGUSER', 'postgres'),
      password: env('PGPASSWORD', 'password'),
      ssl: env.bool(true),
    },
  },
});

To confirm everything goes well, run a production build with:



# npm
ENV_PATH=./.env.production NODE_ENV=production npm run start

# yarn
ENV_PATH=./.env.production NODE_ENV=production yarn start

If everything goes well, you should be able to open the admin panel at http://0.0.0.0:1337/admin:

The next step is to make your Strapi project a git repository and push to Github. So that we can deploy on Railway from our repo.

Go back to your project on Railway, Click on the New button, choose the Github Repo option, then you should choose your Strapi app repo.

At this point, the build will fail for two reasons:
- Because Railway resolved to a node version that Strapi doesn't support. (Strapi doesn't support odd-number releases of Node e.g. v13, v15. From the log, Strapi is picking up v15. Yikes).

- We haven't added our environment variables to Railway. Strapi needs these to run.

To fix the first issue, change the loose node version specified by default in package.json of your Strapi project.



//package.json
"engines": {
  "node": ">=12.x.x <=16.x.x",
  "npm": ">=6.0.0"
 },

To something more specific like v16.4.2 (a LTS version of Node)



//package.json
"engines": {
  "node": "16.14.2",
  "npm": ">=6.0.0"
 },

Now commit and push. Railway auto deploys on new git commits, our build will still fail as you haven't provided the necessary enviroment variables.

Go to the Variables tab of the Strapi deployment on Railway. Click on the 'Bulk Import' button. Paste in all the contents of the .env.production file you created earlier.

If everything goes well, our build should now be successful. You should be assigned a Service domain like project-name.up.railway.app. which you can go on to customize.

Forem: Yinka Adedire

Implementing Authorization with Clerk in a tRPC app running on a Cloudflare Worker

Prerequisites

Authorization Strategy

Set up tRPC

Install tRPC

Create a tRPC router

Create a Cloudflare Worker project

Startup the tRPC server with Cloudflare Worker

Handle CORS and CORS preflight requests

Integrate Clerk with tRPC

Install Clerk Backend SDK

Set environment secrets

Using Clerk in your tRPC Context

Create a tRPC auth middleware

Create a route that requires authentication

Deploy your tRPC API

Testing everything out

Create a NextJS app

Set Up Clerk In Your NextJS App

Setup tRPC in your NextJS app

Create tRPC hooks

Setup tRPC Provider

Wrap your NextJS app in the tRPC provider

Make a request to your tRPC API

Wrapping up

Resources

How to make Radix UI Tabs URL based in NextJS

Requirements

Step 1: Setting Up the Project

Step 2: Creating a Basic Radix UI Tabs Component

Step 3: Integrating with NextJS Router

Conclusion

Resources

How to set up an AWS S3 bucket for Medusa S3 file plugin.

Prerequisites

Create an AWS IAM User and Group

Create new user

Create user group

Login as IAM User

Create S3 Bucket

Install medusa-file-s3

Test It Out

How to Setup A Medusa Server Locally

A Primer On Medusa

Requirements

Install NodeJS

Install the Medusa CLI

Create a Medusa Server Project

Start the Medusa Server

Test It Out

Medusa Server Configuration

Install PostgreSQL

Create Postgres Database

Add the Postgres URL to the environmental variable

Configure Postgres in medusa-config.js

Install Redis

Start Redis Server

Add Redis the Server URL to the environmental variable

Configure Redis in medusa-config.js

Test It Out

Setup A File Storage Plugin

Set up MinIO

Launch MinIO Server

Create a MinIO bucket

Install Medusa MinIO Plugin

Test it Out

How To Integrate Gatsby with Shopify using Shopify Custom Apps

Create A Shopify Account

Setup A Shopify Store.

Setup Shopify Custom app

Configure Admin API Scopes

Configure Storefront API Scopes

Install the App

Setup Gatsby.js site

Store API Credentials from Shopify

Install and setup plugin

Fire it up

Resources

How to create and deploy a Strapi project on Railway

Install `medusa-file-s3`

Configure Postgres in `medusa-config.js`