DEV Community: Deniz Ozkan

Next.js and server side Firebase Authentication Journey

Deniz Ozkan — Mon, 08 Jan 2024 09:00:00 +0000

In this journey, we're diving into setting up session-based authentication using Firebase Auth and Next.js 14.
Instead of checking a user's auth state on the client side like Firebase intended, we're taking it up a notch by doing it on the server.
We can check the auth state directly in the server before sending our response to the client. No more useEffect calls and re-rendering components to reflect the auth state of the user.

Server Environment and Firebase

Firebase is a client side package and not suitable for our needs. It provides a safe way to handle auth in the client for those applications without a backend. In this tutorial though, we have a backend and want to use serverActions and server side logic to determine auth state of the user. We rely on firebase/auth for user credential management instead of rolling our own auth service which is quite risky and complicated.

To run firebase operations in the server, we must use firebase-admin library provided by firebase. It targets a node.js environment which is the environment of next.js server actions and components unless we specify runtime="edge".

middleware auth?

I know some of you may want to authenticate a request using the middleware.ts but beware that the firebase-admin package only runs in nodejs environment and wont work in the middleware which only supports runtime="edge".

Project Outline

In this basic auth demonstration, we will implement these:

Sign in using firebase/auth client side library and providers (google, github etc)
Ability to Sign out / delete account using server actions
Ability to read user information and auth state in the server before rendering.

Here are the routes used in the project. I've omitted the components etc. You may view them in the repo.

app
 ├─> _components/
 ├─> _hooks/
 ├─> user/
 |   ├─> login/
 |   |   └── page.tsx
 |   ├─> logout/
 |   |   └── page.tsx
 |   ├── actions.tsx
 |   ├── page.tsx
 ├── global.css
 ├── layout.tsx
 └── page.tsx

Getting Started

Im skipping the part where we initialize a new next.js project with typescript and tailwind and delete the pre-generated content.
We just need the firebase packages to get started: npm i firebase firebase-admin.
Now we need 2 firebase app instances. One for the client side and one for the server side.

Initialize firebase client app

Lets create a /lib folder in our root directory and make a new file for the client side firebaseApp instance.
We will initialize a firebase app and create an auth object as well.

To get these values, first create a new firebase app using the firebase console then select the web application to generate these.
I've stored the values in my .env file for ease of use.

// Import the functions you need from the SDKs you need
import { FirebaseOptions, getApp, getApps, initializeApp } from "firebase/app";
import { getAuth, inMemoryPersistence } from "firebase/auth";

// Firebase configuration
const firebaseConfig: FirebaseOptions = {
    apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
    authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
    storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
    //If google analytics is enabled, provide this in the .env
    measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
};

// Initialize Firebase or get the already available instance (singleton pattern)
const app = getApps().length >= 1 ? getApp() : initializeApp(firebaseConfig);

export default app;

// Initialize Firebase Authentication and get a reference to the service
const auth = getAuth(app);

//Do not persist. We'll use server side sessions to verify auth
auth.setPersistence(inMemoryPersistence);

export { auth };

We are now ready to sign in using firebase. Before continuing go to firebase console, enable authentication and add google as a provider so we can login using google accounts.

Login using firebase and google provider

To get a users credential, we must initiate a sign in flow using one of the firebase providers. Assuming we have enabled google as an auth provider in the firebase console, lets create a basic login page at user/login/page.tsx

export default async function LoginPage() {
    return (
        <section className="p-2 md:p-4 max-w-[60ch] mx-auto mt-10 ">
            <h2 className="font-medium py-2 text-xl tracking-tighter text-center">
                Login to continue
            </h2>
            <p className="py-2 leading-relaxed text-center">
                Please sign in to the app using one of the providers. You will
                have the option to delete your account anytime you want.
            </p>
            <div className="grid grid-flow-row max-w-sm gap-2 mt-10 mx-auto">
                {/* Providers */}
                <GoogleSignIn />
            </div>
        </section>
    );
}

As you can see this is a server component. We need a client component for the firebase sign in flow. Lets create the <GoogleSignIn /> button as a client component to handle sign in using a popup as explained in firebase/auth documentation.

Note that the actual component has some additional features like loading state and error handling. Please view the repo for details

"use client";
//... import required functions

export default function GoogleSignIn() {
    /**
     * Handle google sign in flow.
     */
    async function signInWithGoogle() {
        try {
            //Initialize the login flow using popup window
            const provider = new GoogleAuthProvider();
            const credentials = await signInWithPopup(auth, provider);

            //If login success, we can extract the JWT token from the credentials object
            const token = await credentials.user.getIdToken();

            //We now send the jwt token to the server to create a session cookie
            const result = await loginAction({ idToken: token });

            //If success, redirect to user profile (This can be done via the server action as well)
            if (result) {
                redirect("/user");
            }
        } catch (error: any) {
            //Display desired errors if needed and reset loading states
        }
    }

    return (
        <div className="flex flex-col w-auto gap-1">
            <button type="button" className="..." onClick={signInWithGoogle}>
                Sign in with Google
            </button>
        </div>
    );
}

As you may have noticed, this client button will call a server action loginAction if firebase auth succeeds.
We need to implement the server side of things for this to work but you can just comment that line out and console.log(token) to verify login was successful.

Firebase-Admin SDK

To access the server side methods of firebase, lets create a lib/firebase-admin.ts file and initialize a firebaseApp which we can use in the server environment.

import "server-only"; // Ensures this file cant be imported in the client
import { initializeApp, getApps, cert } from "firebase-admin/app";
import { getAuth } from "firebase-admin/auth";
import { getFirestore } from "firebase-admin/firestore";

let serviceAccountDetails = {};
try {
    //Decode the base64 encoded json
    const decodedJson = atob(process.env.FIREBASE_CERT_JSON);
    //parse the json
    serviceAccountDetails = JSON.parse(decodedJson);
} catch (error) {
    console.log("Unable to parse the json data for FIREBASE_CERT_JSON");
    throw new Error("Failed to init");
}
const firebaseAdminConfig = {
    credential: cert(serviceAccountDetails),
};

const firebaseAdminApp =
    getApps().find((app) => app.name === "fb-admin") ||
    initializeApp(firebaseAdminConfig, "fb-admin");

const db = getFirestore(firebaseAdminApp);
const auth = getAuth(firebaseAdminApp);

/* --------------------------------- exports -------------------------------- */
export { firebaseAdminApp, auth as adminAuth, db };

To connect to firebase using the admin sdk, go to project settings > service accounts and generate a private key.
We need to read this json file to connect to firebase-admin but this is a problem when deploying the app. We somehow need to store this json data in the .env so we can easily access it.

How to save service account json as environment variable

The solution implemented in this example expects a base64 encoded string from the .env named process.env.FIREBASE_CERT_JSON.
It'll first decode the string and then it'll run JSON.parse and get the original json. But for this to work we need to convert our service account json to a string and encode it in base64. In the repo you'll see a credential.js file to see how its can be achieved. After placing your json file in the /private directory and pasting its name in the credential.js, run node credential.js to generate the base64 encoded string in the /private folder. You may now copy and paste this string to your .env file and access it using process.env.FIREBASE_CERT_JSON

Server Actions

Now that we have our admin app ready, we can create the login action to call when signing in. Lets create user/actions.ts and mark it as "use server" so next.js knows these are server actions.

/**
 * Get the token from the client and save it as a firebase cookie. If login succeeds, revalidate the whole router
 */
export async function loginAction({ idToken }: { idToken: string }) {
    try {
        if (!idToken) return;
        const result = await login(idToken);
        if (result) {
            revalidatePath("/");
            return result;
        }
    } catch (error: any) {
        console.log("loginAction Error: ", error?.message);
        return undefined;
    }
}

Notice how we call revalidatePath("/") so the router and server cache is revoked. Without this, our auth state would not be reflected in the server components without a hard refresh.

In this server action we call the login function. Lets create this function in lib/firebase-auth-api.ts. We can use this file to store all firebase-admin/auth related functions like login, logout etc...

import "server-only";
import { adminAuth } from "./firebase-admin";
import { cookies } from "next/headers";

/**
 * Sign a user in
 * @param token jwt token string from client side.
 * @returns
 */
export async function login(token: string) {
    try {
        //Verify the token and get user data
        const decodedIdToken = await adminAuth.verifyIdToken(token);
        if (!decodedIdToken) return;

        //Create the cookie token string to save.
        const sessionCookie = await adminAuth.createSessionCookie(token, {
            expiresIn: 60 * 60 * 24 * 7 * 1000,
        });

        //Create the cookie
        cookies().set("__session", sessionCookie, {
            maxAge: 60 * 60 * 24 * 7, // 1 week in seconds (Im not sure but this must be in seconds instead of ms)
            httpOnly: true,
            secure: true,
        });

        //User logged in
        return true;
    } catch (error: any) {
        console.log("Error logging in", error?.message);
        return false;
    }
}

With this last part implemented, our sign in page should now work.

Request flow

When we successfully sign in at the client side, we extract the token and send it to loginAction server action.
Server action then uses the login() function to verify the token using admin sdk.
If all succeeds, a cookie is created and sent back to the user.
Further requests will now include the cookie in the headers and we can write another server action to verify user auth state using this cookie we receive in the request.

Verify auth state and get user data

Now that we are logged in, how do we protect routes / get the user data if exists in server components?
Lets create isLoggedIn and getCurrentUser helper functions in our firebase-auth-api

/**
 * Load the token from the session cookie and verify token is valid.
 * @param checkForRevocation Perform a backend query to see if token is revoked?
 * This is a costly operation. It'll connect to firebase backend to validate the account status.
 * You may use this in highly sensitive routes for extra protection.
 * @returns A decoded id token or undefined
 */
export async function isLoggedIn(checkForRevocation = true) {
    try {
        //Get current session cookie if available
        const sessionCookieValue = await getSessionCookie();
        if (!sessionCookieValue) return;

        //Verify cookie token and return Decoded ID Token
        return await adminAuth.verifySessionCookie(
            sessionCookieValue,
            checkForRevocation,
        );
    } catch (error: any) {
        //If there is a problem with the user auth, handle here
        //console.log(error.code) //example: auth/user-disabled
        //delete the cookie and revoke the session
        await logout();
        return undefined;
    }
}

/**
 * Get current user record if found
 * @returns
 */
export async function getCurrentUser(): Promise<UserRecord | undefined> {
    try {
        //load decoded id token without revocation verification call
        const decodedIdToken = await isLoggedIn(false);
        if (!decodedIdToken) return;

        //Load user record using uid from the token
        return await adminAuth.getUser(decodedIdToken.uid);
    } catch (error: any) {
        console.error("Error getCurrentUser", error?.message);
    }
    return undefined;
}

With these functions, we may now verify our session before rendering a component. Note that isLoggedIn will only validate the cookie if checkForRevocation param is false. Is is recommended by firebase that we shouldn't invoke revalidate in every request because it'll hit the backend each time. Only do this when needed in sensitive areas or before sensitive operations.

Protected Routes

We need a new server action to get our auth state in actions.ts

/**
 * Get a UserRecord as JSON object or undefined
 * @param validate query the backend to check if the token is valid? It's a costly operation and must not be called in every page
 * @returns
 */
export async function getAuthAction(validate = false) {
    try {
        if (validate) {
            const decodedIdToken = await isLoggedIn(true);
            if (!decodedIdToken) return undefined;
        }
        const user = await getCurrentUser();
        if (user) return user.toJSON();
    } catch (error: any) {
        console.log("getAuthAction Error: ", error?.message);
        return;
    }
}

Lets create our /user/page.tsx which will show our user profile data using the getAuthAction.
Lets make it so that if we are not logged in, we are redirected to login page.

import { getAuthAction } from "./actions";
import { redirect } from "next/navigation";
import { UserRecord } from "firebase-admin/auth";

export default async function UserPage() {
    const user = (await getAuthAction()) as UserRecord | undefined;
    if (!user) {
        return redirect("/user/login");
    }

    return (
        <section className="mt-10 p-2">
            {/* Card Wrapper */}
            <div className="border rounded-md bg-slate-50 overflow-hidden max-w-2xl mx-auto">
                {/* Card Header */}
                <div className="flex flex-row gap-2 items-center bg-zinc-200 justify-between p-2">
                    <h3 className="font-bold flex-1 ">
                        &#128100; Profile Details
                    </h3>
                    {/* Additional Action buttons can be inserted here later */}
                </div>

                {/* Card Body */}
                <div className="flex flex-col items-center md:flex-row w-full p-2 text-sm gap-10">
                    {/* User Profile Image */}
                    {user.photoURL && (
                        <div className="w-1/4 flex flex-col items-center justify-center gap-1">
                            <img
                                src={user.photoURL}
                                alt="User image"
                                className="rounded-full w-auto"
                                referrerPolicy="no-referrer"
                            />
                            <span className="font-medium">
                                {user.displayName}
                            </span>
                        </div>
                    )}

                    {/* User Details */}
                    <div
                        className="grid gap-y-2 gap-x-4 flex-1 overflow-hidden text-ellipsis"
                        style={{ gridTemplateColumns: "auto 1fr" }}>
                        {/* Row */}
                        <span className="font-medium">Name</span>
                        <span>{user.displayName}</span>
                        {/* Row */}
                        <span className="font-medium">Email</span>
                        <span>{user.email}</span>
                        {/* Row */}
                        <span className="font-medium">Registration Date</span>
                        <span>{user.metadata.creationTime}</span>
                        {/* Row */}
                        <span className="font-medium">Auth Provider</span>
                        <span>
                            {user.providerData[0]?.providerId ?? "Unknown"}
                        </span>
                    </div>
                </div>
            </div>
        </section>
    );
}

As you can see we can check for a user in 1 line and redirect if not found! Note that this must be done using a serverAction like we did here using getAuthAction or calling revalidatePath when we say logout may not refresh data in this route.

Logging Out

Now that we have a way of verifying auth, lets create a server action and a logout function

actions.tsx

/**
 * Initiate logout sequence and redirect to home page if succeeds.
 * @returns
 */
export async function logoutAction(): Promise<undefined> {
    let result: true | undefined = undefined;
    //Call logout and revoke user
    try {
        result = await logout();
    } catch (error: any) {
        console.log("logoutAction Error: ", error?.message);
    }
    //If logout succeeds, redirect
    if (result) {
        revalidatePath("/");
        //Server action is capable of redirecting the client to another route
        //It must not be wrapped in try catch block.
        return redirect("/?notify=logout_success");
    }
    return undefined;
}

As you can see, we can directly initiate a redirect through a server action. Make sure not to wrap it in try-catch block because server action redirects work using throwing NEXT_REDIRECT error object.

Lets also create the logout logic in the firebase-auth-api.ts

/**
 * Log the user out, delete the session cookie, revoke the token
 * @returns
 */
export async function logout() {
    try {
        //Get current session cookie if available
        const sessionCookieValue = await getSessionCookie();
        if (!sessionCookieValue) return;

        //Decode cookie to verify
        const decodedIdToken = await adminAuth.verifySessionCookie(
            sessionCookieValue,
        );

        //Revoke the token
        await adminAuth.revokeRefreshTokens(decodedIdToken.sub);

        //Delete the cookie
        cookies().delete("__session");

        return true;
    } catch (error: any) {
        console.error("Error logOut", error?.message);
    }
}

Avoiding Stale Cache

As mentioned before, when our auth state changes, for the server components to re-render, we must call the revalidatePath function in a server action when necessary. If we don't clear the cache, when we visit /user after logging out, we may still see our user data as stil authenticated. revalidatePath('/user') will remove the cache and re-render this page so we will not be able to see our profile.

Note that there is still some problems with this granular revalidating approach. It's said to be working in the server side cache but when we call revalidatePath, the whole client router cache will be revoked. See this github comment

Conclusion

Many more features can be implemented and more firebase features can be used in the application. Visit the completed project repo or working example for details. Note that, you can delete your account after logging in.

Deploying a Next.js 14 application to Github Pages using static export

Deniz Ozkan — Thu, 28 Dec 2023 21:00:00 +0000

In an earlier adventure, we created a statically generated Next.js blog using Next.js 14, Tailwind Typography and MDX.
If you want more information, you may view that post here.

This time, we are exploring the option to host our static blog site on Github Pages.
Github Pages allows free users to host their static websites if the repository is public which is a great option for our endeavour.
There are some usage limitations for github-pages that you might want to read here before we continue.

Github Repo

If you want to visit the final product and explore the code yourself or just clone the project and make your own blog, go to the github repo here.

You may also visit the blog site deployed to github-pages in its final form here.

First steps

Weather you are using the mdx-blog project or your own next.js project; there are a few things we need to make sure before continuing.

Make sure next is configured to export static site. Go to your project root and open your next.config.js or next.config.mjs

//next.config.mjs
const nextConfig = {
    pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
    //Other configurations
    ...
    output: "export", // This option must be set for static exports.
};

Verify build

We should run next build command to verify that nothing fails and we get our static site at /out folder. When we run a build, next will show the route structure in a tree. All routes must be static since we are pre building each possible route.

Here is what it should look like after a build in the terminal

> next-mdx-static-blog@0.1.0 build
> next build

   ▲ Next.js 14.0.4

 ✓ Creating an optimized production build
 ✓ Compiled successfully
 ✓ Linting and checking validity of types
 ✓ Collecting page data
 ✓ Generating static pages (8/8)
 ✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    178 B          88.9 kB
├ ○ /_not-found                          869 B          82.8 kB
├ ○ /blog                                178 B          88.9 kB
└ ● /blog/[blogId]                       292 B            89 kB
    ├ /blog/first_blog
    └ /blog/second_blog
+ First Load JS shared by all            81.9 kB
  ├ chunks/938-cd2116519108597b.js       26.8 kB
  ├ chunks/fd9d1056-735d320b4b8745cb.js  53.3 kB
  ├ chunks/main-app-6826a28d43c854be.js  219 B
  └ chunks/webpack-71ab42c6f89d781b.js   1.65 kB


○  (Static)  prerendered as static content
●  (SSG)     prerendered as static HTML (uses getStaticProps)

After we make sure our build doesn't fail, all routes are static and our next config is set to output: "export", we may continue.

Configuring the Github Repo

Now that our project is ready for publishing, we commit our changes and upload it to our github repo. Lets now make sure in the repository settings that the visibility is set to public if your account is also a free tier.

Go to settings tab in your github repo and click on pages from the side menu
Select Github Actions
We may now choose a deployment template. A next.js template is suggested already so we choose it or we can just click browse and find the next.js template ourselves.
click customize and view the yaml file that'll deploy our project.

Now you may click on commit changes and try your luck but it didn't work for me because at the time I was writing this blog, the suggested workflow was configured for an older next.js version.

If the build fails

We can go to our code editor now and fetch the new workflow to our project from the github repo.
.github/workflows/nextjs.yml file appears in my project. Lets fix this now

This part is the first culprit. It's writing over our own next.config. We need to remove this step.

#.github/workflows/nextjs.yml
...
- name: Setup Pages
  uses: actions/configure-pages@v4
  with:
      # Automatically inject basePath in your Next.js configuration file and disable
      # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
      #
      # You may remove this line if you want to manage the configuration yourself.
      static_site_generator: next
...

The second culprit is this part that belongs to an older version. We only use the next build command now. So this part must be removed:

...
- name: Static HTML export with Next.js
  run: ${{ steps.detect-package-manager.outputs.runner }} next export
...

Final workflow

Here is what my final workflow looks like. Lets save it and see if the build works.

# github/workflows/nextjs.yml
#
# To get started with Next.js see: https://nextjs.org/docs/getting-started
#
name: Deploy Next.js site to Pages

on:
    # Runs on pushes targeting the default branch
    push:
        branches: ["master"]

    # Allows you to run this workflow manually from the Actions tab
    workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
    contents: read
    pages: write
    id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
    group: "pages"
    cancel-in-progress: false

jobs:
    # Build job
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Detect package manager
              id: detect-package-manager
              run: |
                  if [ -f "${{ github.workspace }}/yarn.lock" ]; then
                    echo "manager=yarn" >> $GITHUB_OUTPUT
                    echo "command=install" >> $GITHUB_OUTPUT
                    echo "runner=yarn" >> $GITHUB_OUTPUT
                    exit 0
                  elif [ -f "${{ github.workspace }}/package.json" ]; then
                    echo "manager=npm" >> $GITHUB_OUTPUT
                    echo "command=ci" >> $GITHUB_OUTPUT
                    echo "runner=npx --no-install" >> $GITHUB_OUTPUT
                    exit 0
                  else
                    echo "Unable to determine package manager"
                    exit 1
                  fi
            - name: Setup Node
              uses: actions/setup-node@v4
              with:
                  node-version: "20"
                  cache: ${{ steps.detect-package-manager.outputs.manager }}

            - name: Restore cache
              uses: actions/cache@v3
              with:
                  path: |
                      .next/cache
                  # Generate a new cache whenever packages or source files change.
                  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
                  # If source files changed but packages didn't, rebuild from a prior cache.
                  restore-keys: |
                      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
            - name: Install dependencies
              run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
            - name: Build with Next.js
              run: ${{ steps.detect-package-manager.outputs.runner }} next build

            - name: Upload artifact
              uses: actions/upload-pages-artifact@v3
              with:
                  path: ./out

    # Deployment job
    deploy:
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
            - name: Deploy to GitHub Pages
              id: deployment
              uses: actions/deploy-pages@v4

Perfect it worked and we can go to https://<username>.github.io/<repository-name>/ to view the blog.
But we have a problem. Because we removed the basePath step from the workflow, all url's in our application are broken including links to css files. We can only see the raw text as you can see below.

Fixing our basePath

If you are hosting your app at the root level of a url like yourblog.com/ there wont be any issues. You can connect a custom domain to your github pages and it'll work. But if you want to be able to host your blog using your github url like https://<username>.github.io/<repository-name>/ we must tell our application that the basePath is /<repository-name>. This will fix all the relative url's.

//next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
    // Configure `pageExtensions`` to include MDX files
    pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
    // Optionally, add any other Next.js config below
    output: "export", // Will export all routes as static html
    basePath: "/next-mdx-static-blog", // <-- replace with your repo name.
};

Et voila! all relative url's are now working

How it all works

Thanks to github workflows, we've just implemented our continuous integration and continuous deployment (CI/CD) pipeline.
When we make a change like add a new mdx file blog post and commit our repo to github, github actions will start thew workflow process.
It'll create a virtual machine, install all our dependencies, run the next build command and deploy the /out folder to github-pages.
Once we've set this up, everything is automated and we get all this for free. Thanks GitHub!

Creating a static Next.js 14 Markdown Blog - An Adventure

Deniz Ozkan — Mon, 25 Dec 2023 13:35:04 +0000

If you wanted to host a personal website with a blog but didn't want to utilize a backend to fetch the blog posts from a database,
you probably explored the markdown option before.
In this guide, I'll share my experience creating a content management system using Next.js 14 and MDX.

Github Repo

If you want to visit the final product and explore the code yourself or just clone the project and make your own blog, go to the github repo here.

Overview

In this development guide we will create a Next.js 14 app router project with static exports
We will utilize the MDX library to render Markdown blog posts.
We will create our first Markdown blog post.

What is Static Site Generation (SSG)

To summarize; Next.js can generate an individual html file for each route in the application.
If a route is a dynamic route like /blog/[...blogId] then you need to generate each possible blogId for that path.
This approach enables us to run the next build command and get the generated full website in the /out folder.
You can just copy the contents of that folder and host it on any webserver as a static site.

Learn more here at the official Next.js documentation

What is Markdown and MDX

Markdown is a text markup language. It's widely adapted. For example, github repo's will detect the readme.md file in the current directory and display it below.

MDX is a js library that allows us to import a markdown file as a react component and use it anywhere.

We will write our blog posts using markdown syntax and save them as an mdx file.
We can then import the post and use it anywhere in our app thanks to these tools.

Getting Started

Lets create a new next.js app using the terminal and choose the default options including tailwind and app router.

npx create-next-app@latest

We can now remove default content from layout.tsx, page.tsx and globals.css. and create a basic root layout

//Layout.tsx
import type { Metadata } from "next";
import "./globals.css";
import Link from "next/link";

export const metadata: Metadata = {
    title: "Next.js Mdx Static Blog",
    description: "A Next.js 14 & MDX blog starter project.",
};

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body className="bg-white dark:bg-zinc-800 text-black dark:text-white">
                {/* Navbar */}
                <header className="h-16 flex flex-row gap-4 justify-between border-b shadow-sm fixed top-0 left-0 w-full bg-slate-200 dark:bg-zinc-900 dark:border-black">
                    <Link href={"/"}>
                        <h1 className="p-4 text-2xl font-bold">NextBlog</h1>
                    </Link>
                    <nav className="flex-1 flex flex-wrap p-4 items-end justify-end gap-4 text-lg font-semibold ">
                        <Link href={"/"} className="underline">
                            Home
                        </Link>
                        <Link href={"/blog"} className="underline">
                            Blog
                        </Link>
                    </nav>
                </header>
                {/* Main Content */}
                <main className="mt-16">{children}</main>
            </body>
        </html>
    );
}

Remove styles

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

Page.tsx is the home / directory of the page.

export default function Home() {
    return (
        <div className="container mx-auto p-4">
            <h2 className="text-xl font-medium">Welcome to my Next.js Blog</h2>
            <p className="mt-2 tracking-wide leading-relaxed">
                Lorem ipsum dolor sit amet consectetur adipisicing elit. Rerum
                enim debitis, repellendus ipsum iusto tempora, commodi inventore
                sed, eius exercitationem laudantium nihil. Maxime exercitationem
                sit dolores dolorum quis, similique id.
            </p>
        </div>
    );
}

Creating the file structure

Lets create our file structure for our rotes and the folder where our markdown blog posts will live.
The blog/[blogId]/page.tsx file will be called when we are viewing a blog post and the blog/page.tsx will be the page to display all blog post links. /blogs folder will keep our MDX files.

/app
└──  blog
    ├── [blogId]
    │   └── page.tsx
    └── page.tsx
/blogs
└──  first_blog.mdx

Installing MDX and Tailwind Typography

To enable viewing MDX files in our app, lets install MDX.
We should also install our other helper which is tailwindcss/typography as a dev dependency.
This'll be useful later for auto styling the blog post.

npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx
npm install -D @tailwindcss/typography

Lets now create a sample MDX file at /blogs/<post_name>.mdx.

# My first Blog Post

Duis adipisicing ad pariatur cupidatat consequat pariatur reprehenderit proident culpa. Est aliqua consectetur velit Lorem minim dolore ipsum id sunt. Velit nisi irure mollit officia pariatur excepteur occaecat duis aliqua id minim duis. Officia eu fugiat irure laborum dolore. Veniam ipsum labore nisi aliquip officia do sunt.

Before we start using the mdx content, we must configure Next.js

MDX Component file

Lets create the necessary mdx-components.tsx file at the root directory next to /app etc.
This will be auto imported by MDX and the components in this will be used to wrap each markdown element
when rendering the mdx content in jsx. If you want to customize a specific element like an h1, this is the place to do it. For further information, visit next.js docs.

import type { MDXComponents } from "mdx/types";

export function useMDXComponents(components: MDXComponents): MDXComponents {
    return {
        ...components,
    };
}

Next Config for MDX and Static Exports

We need to configure next.config.js but if we want markdown plugins like remark-gfm which allows Github flavoured markdown to be rendered, we need to rename the next.config.js file to next.config.mjs

Lets first install remark-gfm npm i remark-gfm so we can use enhanced markdown features of Github flavoured markdown.

Lets also configure next.js to use static exports by adding output: "export" to the config object.

import remarkGfm from "remark-gfm";
import createMDX from "@next/mdx";

/** @type {import('next').NextConfig} */
const nextConfig = {
    // Configure `pageExtensions`` to include MDX files
    pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
    // Optionally, add any other Next.js config below
    output: "export", // Will export all routes as static html
};

const withMDX = createMDX({
    // Add markdown plugins here, as desired
    options: {
        remarkPlugins: [remarkGfm],
        rehypePlugins: [],
    },
});

// Merge MDX config with Next.js config
export default withMDX(nextConfig);

Generating static pages

Before we can continue, if we now visit /blog/first_blog our app will throw an error because we are now using static site generation. We must provide the route with all possible blogId's in a function called
generateStaticParams.

Lets go to blog/[blogId]/page.tsx and manually create one. we will later come back to this.

import React from "react";

/**
 * return all possible blogId values in an array like [{blogId: 'first_blog'}, {blogId: 'second_blog'}]
 */
export async function generateStaticParams() {
    const blogPosts = ["first_blog"];
    return blogPosts.map((post) => ({
        blogId: post,
    }));
}

type BlogPageProps = {
    params: { blogId: string };
};

export default function BlogPage({ params }: BlogPageProps) {
    return (
        <div className="container mx-auto p-4">
            <h2 className="text-xl font-medium">BlogId: {params.blogId}</h2>
            <p>...</p>
        </div>
    );
}

Now we can visit blog/first_blog. Please note that visiting any other blogId will result in an error in dev server but it will just show a 404 error page in production (after build).

Rendering our first blog

We are now ready to import our markdown file and render it! Reminder: make sure you've created the mdx-components.tsx at the root directory.

We need to use next/dynamic to import our markdown as a component in blog/[blogId]/page.tsx

import dynamic from "next/dynamic";
import React from "react";

/**
 * return all possible blogId values in an array like [{blogId: 'first_blog'}, {blogId: 'second_blog'}]
 */
export async function generateStaticParams() {
    const blogPosts = ["first_blog"];
    return blogPosts.map((post) => ({
        blogId: post,
    }));
}

type BlogPageProps = {
    params: { blogId: string };
};

export default async function BlogPage({ params }: BlogPageProps) {
    const BlogPost = dynamic(() => import("@/blog/" + params.blogId + ".mdx"));

    return (
        <div className="container mx-auto p-4">
            <article>
                <BlogPost />
            </article>
        </div>
    );
}

When we now visit blog/first_blog we should see our blog post rendered in the layout.

Adding Meta Data to blog posts

Since we are using mdx, we can export anything from a mdx file like a normal js file.
Lets export a const called metadata and define some metadata for each blog post there.

export const metadata = {
    title: "My first blog post",
    description: "An awesome blog post about important stuff",
    date: new Date('2023-12-24'),
    author: 'donis.dev'
};

### My first Blog Post

Duis adipisicing ad pariatur cupidatat consequat pariatur reprehenderit proident culpa.
Est aliqua consectetur velit Lorem minim dolore ipsum id sunt.
Velit nisi irure mollit officia pariatur excepteur occaecat duis aliqua id minim duis.
Officia eu fugiat irure laborum dolore. Veniam ipsum labore nisi aliquip officia do sunt.

Blog Helper Functions

Now that we have exports from a mdx file, we need a way to import that file and access its exports.
We need to do this on both blogs page and individual blog post pages so we can create a few helper functions to streamline this process.

lets create a /lib folder and our helper functions file /lib/blog_functions.ts

/**
 * Import an mdx blog post file and return the metadata.
 * @param blogId
 * @returns
 */
export async function getPostData(blogId: string): Promise<{
    id: string;
    title: string;
    description: string;
    date: Date;
    author: string;
}> {
    //Lazy load the mdx file for the project
    try {
        const file = await import("@/blog/" + blogId + ".mdx");

        if (file?.metadata) return file.metadata;
        else {
            throw new Error(`Unable to find metadata in file ${blogId}.mdx`);
        }
    } catch (error: any) {
        console.log(error?.message);
        //Return empty metadata on failure
        return {
            id: "",
            title: "",
            description: "",
            date: new Date(),
            author: "",
        };
    }
}

we may now use this hook to easily load metadata for any blogId. Lets use this data to display the correct title and description for the blog page.


...
export async function generateMetadata({
    params,
}: BlogPageProps): Promise<Metadata> {
    //Load the blog post metadata using blog_functions.ts
    const metadata = await getPostData(params.blogId);
    if (metadata) {
        return {
            title: metadata.title,
            description: metadata.description,
        };
    }
    return {}; //Default return.
}
...

You will now notice that your page title is loaded from first_blog.mdx metadata.

Styling the post: Tailwind Typography

We had installed the tailwind typography plugin before. Now we can use it to easily style our blog post.
In the <article> tag wrapping the blog post, lets add the following classes:

...
<article className="prose w-full mt-10 dark:prose-invert">
    <BlogMarkdown />
</article>
...

now for this to work, me must configure tailwind config. Go to your project root and open tailwind.config.ts and add the typography plugin to plugins array.

import type { Config } from "tailwindcss";

const config: Config = {
    content: [
        "./pages/**/*.{js,ts,jsx,tsx,mdx}",
        "./components/**/*.{js,ts,jsx,tsx,mdx}",
        "./app/**/*.{js,ts,jsx,tsx,mdx}",
    ],

    plugins: [require("@tailwindcss/typography")],
};
export default config;

after reloading the dev server, when we visit blog/first_blog we should now see a styled blog page.

Generating the blog list

Now that we are able to view each blog post, lets figure out a way to generate a list of blog posts to show at /blog page.

lets go to /lib/blog_functions.ts and create a function that uses the node filesystem fs to search entire /blog directory and return an array of blogId's available for us.

...
/**
 * import each post in blog directory and return their metadata in an array
 * @returns
 */
export async function getPostsData(): Promise<
    {
        id: string;
        title: string;
        description: string;
        date: Date;
        author: string;
    }[]
> {
    try {
        //Read the /blog folder at root dir
        const fileList: string[] = readdirSync("./blog/");

        //Load each file
        if (fileList.length > 0) {
            const result = fileList.map(async (file) => {
                //Remove extension to get blogId
                const filename =
                    file.substring(0, file.lastIndexOf(".")) || file;
                //Tro to get metadata
                return { ...(await getPostData(filename)), id: filename };
            });

            return Promise.all(result);
        }
    } catch (error) {}
    return [];
}
...

Now we can import the function in the blogs page and list all blog posts

import { getPostsData } from "@/lib/blog_functions";
import Link from "next/link";
import React from "react";

export default async function Blogs() {
    const blogs = await getPostsData();

    //Case: no posts
    if (blogs.length === 0) {
        return (
            <div className="container mx-auto p-4">
                There are no posts yet...
            </div>
        );
    }
    //Display all posts
    return (
        <div className="container mx-auto p-4">
            <p>Here are my latest blog posts. Enjoy</p>

            <ul className="border-t border-dotted mt-4 py-4 flex flex-col gap-4">
                {blogs.map((blog) => {
                    return (
                        <li key={blog.id}>
                            <Link href={`/blog/${blog.id}`}>
                                {blog.title}
                                <span className="ml-2 text-xs opacity-50">
                                    {blog.date.toLocaleDateString()}
                                </span>
                            </Link>
                        </li>
                    );
                })}
            </ul>
        </div>
    );
}

generateStaticParams for all blog posts

Now only thing left is generating static params for all routes. We need to read all filenames /blog directory and create a static route for each of them in app/blog/[blogId]/page.tsx

Lets first create another helper function to get all filenames from the blog directory

...
/**
 * Scan the blog directory and return an array of file names
 * @returns
 */
export function getPostNames(): string[] {
    try {
        //Read the /blog folder at root dir
        const fileList: string[] = readdirSync("./blog/");
        //Return an array of filenames at this dir
        if (fileList.length > 0) {
            return fileList.map((file) => {
                //Remove extension
                return file.substring(0, file.lastIndexOf(".")) || file;
            });
        }
    } catch (error) {}
    return [];
}
...

Now we can go to our blog page and generate static params

...
/**
 * return all possible blogId values in an array like [{blogId: 'first_blog'}, {blogId: 'second_blog'}]
 */
export async function generateStaticParams() {
    const blogPosts = getPostNames();
    return blogPosts.map((post) => ({
        blogId: post,
    }));
}
...

Conclusion

We now have a working blog. All we need to do to create more posts is to create a new .mdx file at /blog directory. We need to export export const metadata in each post or the app will throw error.

Final blog post example:

export const metadata = {
    title: "My second blog post",
    description: "An awesome blog post about important stuff",
    date: new Date("2023-12-25"),
    author: "donis",
};

### My Second Blog Post

Cillum nostrud veniam enim id enim dolor magna.
Magna occaecat proident ea non Lorem pariatur qui voluptate minim qui dolor Lorem aliquip excepteur.
Consectetur ex aute qui duis velit id velit in eu velit. Laboris voluptate consectetur non deserunt cillum tempor id aliquip officia.

> To be or not to be.

Here is a screenshot of the /blog page

DEV Community: Deniz Ozkan

Next.js and server side Firebase Authentication Journey

Server Environment and Firebase

middleware auth?

Project Outline

Getting Started

Initialize firebase client app

Login using firebase and google provider

Firebase-Admin SDK

How to save service account json as environment variable

Server Actions

Request flow

Verify auth state and get user data

Protected Routes

Logging Out

Avoiding Stale Cache

Conclusion

Deploying a Next.js 14 application to Github Pages using static export

Github Repo

First steps

Verify build

Configuring the Github Repo

If the build fails

Final workflow

Fixing our basePath

How it all works

Creating a static Next.js 14 Markdown Blog - An Adventure

Github Repo

Overview

What is Static Site Generation (SSG)

What is Markdown and MDX

Getting Started

Creating the file structure

Installing MDX and Tailwind Typography

MDX Component file

Next Config for MDX and Static Exports

Generating static pages

Rendering our first blog

Adding Meta Data to blog posts

Blog Helper Functions

Styling the post: Tailwind Typography

Generating the blog list

generateStaticParams for all blog posts

Conclusion

Further reading