The past few weeks I've introduced my library called NextShield and show an example using it with Supabase. Today's example is using NextShield with Clerk, so let's get started 🚀.

Get a Clerk account.

• Go to Clerk's site and click on Sign Up:

• And create your account:

Create a Clerk App.

• Go to your Dashboard and click on Create application:

• Choose Standard Setup:

• Put your App's name and choose a color:

That's it, let's create a Next.js app with NextShield.

Create a Next.js App with NextShield.

For this tutorial you need to create a Next.js app configured with NextShield, to do so, you can follow the instructions of my first post or just clone the repo (clone the main branch).

That's it, let's set up the NextShield with Clerk.

Set Up NextShield with Clerk.

Instal Dependencies.

• First install the clerk package:

npm i @clerk/nextjs

Get API Key.

• Then go to your dashboard and select your app:

• Select the development environment:

• Scroll down a little bit to see the Instance Configuration section to get the Frontend API key:

• Go to your Next.js app and create a .env.local file at the root of the project and setup the following variable with your key:

NEXT_PUBLIC_CLERK_FRONTEND_API="FRONTEND API KEY HERE"

Set URLs.

• Now go back to your Clerk app and click on Settings -> URL & Redirects -> Component URLs:

Enable Use Custom URL on each field and write the following values:

Auth Providers.

• Also in Settings -> User management select your preferred providers.

Bind Next.js & Clerk.

• Open your file _app.tsx and put the ClerkProvider:

import type { AppProps } from 'next/app'

import { ClerkProvider } from '@clerk/nextjs'

import { Shield } from '@/components/routes/Shield'

import '@/styles/globals.css'

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClerkProvider>
      <Shield>
        <Component {...pageProps} />
      </Shield>
    </ClerkProvider>
  )
}

• Update the pages directory with the following folder structure:

• Also update the Nav component adding the sign in & out routes:

import Link from 'next/link'

export function Nav() {
  return (
    <nav>
      <Link href="/">
        <a>Home</a>
      </Link>
      <Link href="/sign-up">
        <a>Sign Up</a>
      </Link>
      <Link href="/sign-in">
        <a>Sign In</a>
      </Link>
      <Link href="/pricing">
        <a>Pricing</a>
      </Link>
      <Link href="/profile">
        <a>Profile</a>
      </Link>
      <Link href="/dashboard">
        <a>Dashboard</a>
      </Link>
      <Link href="/users">
        <a>Users</a>
      </Link>
      <Link href="/users/1">
        <a>Single User</a>
      </Link>
    </nav>
  )
}

• Add the following content for the index.tsx and pricing.tsx files:

import { Layout } from '@/components/routes/Layout'

export default function PageName() {
  return (
    <Layout title="PageName">
      <h1>PageName</h1>
    </Layout>
  )
}

• For the dashboard.tsx, users/index.tsx and users/[id].tsx files, update the content to:

import { Layout } from '@/components/routes/Layout'
import { UserButton } from '@clerk/nextjs'

export default function PageName() {
  return (
    <Layout title="PageName">
      <h1>PageName</h1>

      <div className="flex">
        <UserButton />
      </div>
    </Layout>
  )
}

Finally, add the Clerk components on the pages that we defined in our dashboard:

• For sign-up/[[...index]].tsx:

import { SignUp } from '@clerk/nextjs'

export default function SignUpPage() {
  return (
    <>
      <SignUp path="/sign-up" routing="path" signInUrl="/sign-in" />
    </>
  )
}

• For sign-in/[[...index]].tsx:

import { SignIn } from '@clerk/nextjs'

export default function SignInPage() {
  return (
    <>
      <SignIn path="/sign-in" routing="path" signUpUrl="/sign-up" />
    </>
  )
}

And the profile/[[...index]].tsx:

import { Layout } from '@/components/routes/Layout'
import { UserProfile } from '@clerk/clerk-react'

export default function Profile() {
  return (
    <Layout title="Profile">
      <UserProfile path="/profile" routing="path" />
    </Layout>
  )
}

Bind NextShield & Clerk.

Finally the interesting part 🥳.

• Go to the Shield component and import:

import { useUser } from '@clerk/nextjs'

• Use this hook passing the parameter withAssertions set to true, this is because in that way we can access to isLoading and isSignedIn functions, which are must to have in NextShield parameters.

const { user, isLoading, isSignedIn } = useUser({ withAssertions: true })

• Then update the NextShieldProps with the following:

const shieldProps: NextShieldProps<
    ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    ['/', '/sign-in', '/sign-up']
  > = {
    router,
    isAuth: isSignedIn(user),
    isLoading: isLoading(user),
    privateRoutes: ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/sign-in', '/sign-up'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/sign-in',
    accessRoute: '/dashboard',
    LoadingComponent: <Loading />,
  }

• The complete component should look like this:

import { useRouter } from 'next/router'
import { NextShield, NextShieldProps } from 'next-shield'
import { useUser } from '@clerk/nextjs'

import { Children } from '@/types/Components'
import { Loading } from './Loading'

export function Shield({ children }: Children) {
  const router = useRouter()
  const { user, isLoading, isSignedIn } = useUser({ withAssertions: true })

  const shieldProps: NextShieldProps<
    ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    ['/', '/sign-in', '/sign-up']
  > = {
    router,
    isAuth: isSignedIn(user),
    isLoading: isLoading(user),
    privateRoutes: ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/sign-in', '/sign-up'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/sign-in',
    accessRoute: '/dashboard',
    LoadingComponent: <Loading />,    
  }

  return <NextShield {...shieldProps}>{children}</NextShield>
}

• By now, you should have something like this, you only have access to public and hybrid routes when you're logged out:

• And when logged in you have access to private and hybrid routes, the public routes are inaccessible:

Let's move things further and add RBAC.

Add RBAC.

• Go to Users section on your dashboard and select your user:

• Scroll down until the Metadata section and edit the public data:

• Add the following content and save the changes:

• Go back to the Next.js app and create a new type under types/User.ts:

export type Metadata =
  | {
      role?: string
    }
  | undefined

• That's it, import the type in the Shield component, and create a constant with that type:

  const { user, isLoading, isSignedIn } = useUser({ withAssertions: true })
  const userMetadata: Metadata = user?.publicMetadata

• And define the roles in NextShield 😎

const shieldProps: NextShieldProps<
    ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    ['/', '/sign-in', '/sign-up']
  > = {
    router,
    isAuth: isSignedIn(user),
    isLoading: isLoading(user),
    privateRoutes: ['/profile/[[...index]]', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/sign-in', '/sign-up'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/sign-in',
    LoadingComponent: <Loading />,
    RBAC: {
      ADMIN: {
        grantedRoutes: ['/dashboard', '/profile/[[...index]]', '/users', '/users/[id]'],
        accessRoute: '/dashboard',
      },
      EMPLOYEE: {
        grantedRoutes: ['/profile/[[...index]]', '/dashboard'],
        accessRoute: '/profile/[[...index]]',
      },
    },
    userRole: userMetadata?.role,
  }

• The final app should look like this:

Protect your componentes.

You can move things one step further and protect your components depending on the user's role or a custom condition, even if that user has access to that route.

Test this code in your pricing page and tell me what you think in the comments 😏:

import { useUser } from '@clerk/clerk-react'
import { ComponentShield } from 'next-shield'

import { Layout } from '@/components/routes/Layout'
import { Metadata } from '@/types/User'

export default function Pricing() {
  const { user, isLoading, isSignedIn } = useUser({ withAssertions: true })
  const userMetadata: Metadata = user?.publicMetadata

  return (
    <Layout title="Pricing">
      <h1>Pricing</h1>

      <ComponentShield
        showIf={isSignedIn(user) && !isLoading(user)}
        fallback={<p>You are unauthorized</p>}
      >
        <p>You are authorized</p>
      </ComponentShield>

      <ComponentShield RBAC showForRole="ADMIN" userRole={userMetadata?.role}>
        <p>You are an admin</p>
      </ComponentShield>
    </Layout>
  )
}

Conclusion.

NextShield & Clerk make a perfect symbiosis!!!

• Real-time role change.
• Redirects automatically.
• Absolute 0 flashy content.
• Perfectly protected app.

You can get the completed example here.

Also you can read the complete NextShield series.

Bye!

Hope you like it, see you next time!

Create a new Supabase project.

Go to supabase website and click on "Start your project":

Sign in and click on "New Project":

Fill the form and create the project:

Wait until the project is created:

Configure Supabase.

We need to configure supabase to satisfy our needs with RBAC, so go to the SQL menu and click on new query:

Create the profiles table:

create table public.profiles (
  id uuid references auth.users not null,
  role text,

  primary key (id)
);

And enable row level security to restrict the access:

alter table public.profiles enable row level security;

Then add the following policies to grant user access to their data:

create policy "Users can insert their own profile."
  on profiles for insert
  with check ( auth.uid() = id );

create policy "Users can update own profile."
  on profiles for update
  using ( auth.uid() = id );

Finally, create a trigger to insert a new record when a new user is created:

-- inserts a row into public.profiles
create function public.handle_new_user() 
returns trigger 
language plpgsql 
security definer 
as $$
begin
  insert into public.profiles (id, role)
  values (new.id, "EMPLOYEE");
  return new;
end;
$$;

-- trigger the function every time a user is created
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

For a real project, you want this trigger to be well-tested because if it fails it could block the user sign ups.

Create a new Next.js Project:

To avoid writing boilerplate code you can use the project that we wrote in the previous post, but if you didn't follow that one, you can just clone the repo (clone the main branch).

Install Dependencies.

npm i next-shield @supabase/supabase-js valtio

Change the styles.

Replace the code under styles/globals.css with:

* {
  box-sizing: border-box;
}

html,
body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu,
    Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
  background-color: black;
  color: white;
}

nav {
  display: flex;
  flex-direction: column;
}

@media (min-width: 768px) {
  nav {
    flex-direction: row;
    justify-content: space-evenly;
  }
}

a {
  display: block;
  text-align: center;
  text-decoration: none;
  color: white;
  padding: 1rem;
  transition: all ease-in-out 0.3s;
}

a:hover {
  color: black;
  background-color: #3cce8d;
}

button {
  padding: 0.5rem 1rem;
  margin: 0.5rem;
  cursor: pointer;
  background-color: white;
  color: black;
  border: none;
  font-weight: 700;
  font-size: 1.2rem;
  transition: all ease-in-out 0.3s;
}

button:hover {
  background-color: #3cce8d;
}

.center {
  height: 40vh;
  display: grid;
  place-items: center;
  text-align: center;
}

@media (min-width: 768px) {
  .center {
    height: 90vh;
  }
}

.loading {
  margin: 40vh auto;
}

Setup Supabase in Next.js.

Create a file in the root of the project called .env.local with the following values:

NEXT_PUBLIC_SUPABASE_URL=""
NEXT_PUBLIC_SUPABASE_KEY=""

Then go to your supabase project, scroll down and search for those values:

Create a folder called db with the file client.ts:

And Initialize the client

import { createClient } from '@supabase/supabase-js'

// Create a single supabase client for interacting with your database
export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL as string,
  process.env.NEXT_PUBLIC_SUPABASE_KEY as string
)

Supabase Auth Provider.

Supabase gives you a way of having OAuth2 by providing the secret keys of the auth provider that you're using (Google, Twitter, GitHub, etc.), you can use whatever you want in this example even passwordless auth, in my case I used the google provider, to get the keys you can see the following tutorial:

Get the Google keys

Define the User types.

Go to the file types/User.ts and replace its content with:

export interface UserProfile {
  id: string
  role: string
}

export interface Auth {
  isAuth: boolean
  isLoading: boolean
  user: UserProfile | null | undefined
}

export type AuthStore = {
  updateAuth: (params: Auth) => void
} & Auth

Store.

Create a store folder with an index.ts file:

Then we are going to use the valtio state manager for our store, with the following code:

import { proxy } from 'valtio'

import { supabase } from '@/db/client'
import type { AuthStore } from '@/types/User'

export const authStore = proxy<AuthStore>({
  user: undefined,
  isAuth: !!supabase.auth.user(),
  isLoading: false,
  updateAuth({ isAuth, isLoading, user }) {
    authStore.isAuth = isAuth
    authStore.isLoading = isLoading
    authStore.user = user
  },
})

That's it, the main reason for using valtio is the simplicity of usage and the improvements that it has to avoid unnecessary rerenders.

useAuth Hook.

Create a folder called hooks with an auth.ts file:

Create a function called useAuth:

export function useAuth() {}

Inside of it use the useSnapshot to access to our store:

const { updateAuth, ...state } = useSnapshot(authStore)

Then define the sign in & out functions:

  const signIn = useCallback(async () => {
    await supabase.auth.signIn({ provider: 'google' })
  }, [])

  const signOut = useCallback(async () => {
    await supabase.auth.signOut()
  }, [])

After that add an useEffect and pass the updateAuth method as the only dependency:

  useEffect(() => {

  }, [updateAuth])

Then create a function called getUserProfile to query the user profile:

const getUserProfile = async () => {
      const { data: profile } = await supabase
        .from<UserProfile>('profiles')
        .select('id, role')
        .single()

      if (profile) {
        updateAuth({
          user: profile,
          isAuth: true,
          isLoading: false,
        })

        return
      }

      updateAuth({
        user: null,
        isAuth: false,
        isLoading: false,
      })
    }

The reason why we are not using a filter to get a specific user is because we already defined in our policies that each user owns their data and nobody else.

After defining this function, execute it to make a request when the component mounts and also execute it inside the onAuthStateChange to request the user's data whenever the auth state changes:

getUserProfile()

const { data } = supabase.auth.onAuthStateChange(() => {
   getUserProfile()
})

And also create a subscription to get realtime data:

const profile = supabase
      .from<UserProfile>('profiles')
      .on('UPDATE', payload => {
        updateAuth({
          user: payload.new,
          isAuth: true,
          isLoading: false,
        })
      })
      .subscribe()

And finally unsubscribe when the component unmounts:

    return () => {
      data?.unsubscribe()
      supabase.removeSubscription(profile)
    }

Then just return the functions that we created alongside the state:

return {
    signIn,
    signOut,
    ...state,
  }

Update the pages.

In dashboard.tsx, users/index.tsx and users/[id].tsx add the sign out:

import { Layout } from '@/components/routes/Layout'
import { useAuth } from '@/hooks/auth'

export default function Dashboard() {
  const { signOut } = useAuth()

  return (
    <Layout title="Dashboard">
      <h1>Dashboard</h1>

      <button onClick={signOut}>Sign Out</button>
    </Layout>
  )
}

Add the sign in to the login.tsx page:

import { Layout } from '@/components/routes/Layout'
import { useAuth } from '@/hooks/auth'

export default function Login() {
  const { signIn } = useAuth()

  return (
    <Layout title="Login">
      <h1>Login</h1>
      <button onClick={signIn}>Sign In</button>
    </Layout>
  )
}

Add the changeRole functionality in the profile.tsx page:

import { useCallback } from 'react'
import { Layout } from '@/components/routes/Layout'
import { supabase } from '@/db/client'
import { useAuth } from '@/hooks/auth'

export default function Profile() {
  const { signOut, user } = useAuth()
  const role = user?.role === 'EMPLOYEE' ? 'ADMIN' : 'EMPLOYEE'

  const changeRole = useCallback(async () => {
    await supabase.from('profiles').update({ role })
  }, [role])

  return (
    <Layout title="Profile">
      <h1>Profile</h1>
      <button onClick={signOut}>Sign Out</button>
      <button onClick={changeRole}>Change my user role to {role}</button>
    </Layout>
  )
}

Add ComponentShield in the pricing page:

import { ComponentShield } from 'next-shield'
import { Layout } from '@/components/routes/Layout'
import { useAuth } from '@/hooks/auth'

export default function Pricing() {
  const { user, isAuth, isLoading } = useAuth()

  return (
    <Layout title="Pricing">
      <h1>Pricing</h1>

      <ComponentShield showIf={isAuth && !isLoading}>
        <p>You are authenticated</p>
      </ComponentShield>
      <ComponentShield RBAC showForRole="ADMIN" userRole={user?.role}>
        <p>You are an ADMIN</p>
      </ComponentShield>
      <ComponentShield RBAC showForRole="EMPLOYEE" userRole={user?.role}>
        <p>You are an EMPLOYEE</p>
      </ComponentShield>
    </Layout>
  )
}

Combine Supabase and NextShield.

Go to the Shield.tsx component, import the useAuth hook, and replace the values.

const { user, isAuth, isLoading } = useAuth()

const shieldProps: NextShieldProps<
    ['/profile', '/dashboard', '/users', '/users/[id]'],
    ['/', '/login']
  > = {
    router,
    isAuth,
    isLoading,
    privateRoutes: ['/profile', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/login'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/login',
    LoadingComponent: <Loading />,
    RBAC: {
      ADMIN: {
        grantedRoutes: ['/dashboard', '/profile', '/users', '/users/[id]'],
        accessRoute: '/dashboard',
      },
      EMPLOYEE: {
        grantedRoutes: ['/profile', '/dashboard'],
        accessRoute: '/profile',
      },
    },
    userRole: user?.role, // Must be undefined when isAuth is false & defined when is true
  }

Result.

As an unauthenticated user, you only can access public and hybrid routes:

And when you're authenticated, you only can access hybrid and private routes where you have granted access:

That's it, really simple, you can check the github repo to download this example, and also don't forget to read the docs.

Hope you like it, I'm going to publish an example per week with the most popular auth providers (Clerk, Auth0, etc.), so if you don't wanna miss any article please follow me ;D.

See you next time!

This happens because in the first render React read the auth state as null Why? because in the first render the API request was not resolved yet, is until the second render when React has resolved the request making the change to the state, triggering a rerender but now with the data available.

In summary, React is reading the state values before they are available, getting a falsy value, that's the problem.

How can you solve this? There are many solutions, some people handle that on the frontend and implement a hacky way using windows.location or on the backend with Next.js using the getServerSideProps method on your pages which has a redirect property to force a redirect to another page, and as you know is executed before rendering the page, which is perfect, right? Well... yes but actually no.

If your backend server gets frozen the only thing your user is gonna see is a blank page, because of that you can't give any feedback to your user, not even a spinner, the best solution is still on the frontend, so may you ask "how can I implement the hacky solution using windows.location?" I don't recommend that also, so what solution do I recommend?

The Solution.

Frameworks like Laravel or Ruby on Rails have this solved, so why a cutting-edge framework like Next.js has not resolved this yet? Well, maybe we never know it (or maybe there is a reason for it but I didn't realize), but I crafted my own solution called NextShield:

Philosophy.

• Never deal with authorization code again.
• Never hardcode a redirect, let your state handle it for you.
• Easy To Use.

Features.

• No Flashy Content.
• RBAC.
• Completely Agnostic.

Let's create a simple example to see the API.

NextShield Example.

• Create a new Next.js app:

npx create-next-app --ts shield-example

• Install NextShield:

npm i next-shield

• Install the spinners:

npm i react-epic-spinners

• Copy the following styles in your styles/globals.css file:

* {
  box-sizing: border-box;
}

html,
body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu,
    Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
  background-color: black;
  color: white;
}

nav {
  display: flex;
  flex-direction: column;
}

@media (min-width: 768px) {
  nav {
    flex-direction: row;
    justify-content: space-evenly;
  }
}

a {
  display: block;
  text-align: center;
  text-decoration: none;
  color: white;
  padding: 1rem;
  transition: all ease-in-out 0.3s;
}

a:hover {
  color: black;
  background-color: white;
}

button {
  padding: 0.5rem 1rem;
  cursor: pointer;
  background-color: white;
  color: black;
  border: none;
  font-weight: 700;
  font-size: 1.2rem;
  transition: all ease-in-out 0.3s;
}

button:hover {
  background-color: #00d1ff;
  color: white;
}

.center {
  height: 40vh;
  display: grid;
  place-items: center;
  text-align: center;
}

@media (min-width: 768px) {
  .center {
    height: 90vh;
  }
}

.loading {
  margin: 40vh auto;
}

• Add the following types:

// Components.ts

import type { ReactNode } from 'react'

export interface Children {
  children: ReactNode
}

export type LayoutProps = {
  title: string
} & Children

// User.ts

export interface Profile {
  id: string
  name: string
  role: string
}

• Create the Nav Component:

import Link from 'next/link'

export function Nav() {
  return (
    <nav>
      <Link href="/">
        <a>Home</a>
      </Link>
      <Link href="/login">
        <a>Login</a>
      </Link>
      <Link href="/pricing">
        <a>Pricing</a>
      </Link>
      <Link href="/profile">
        <a>Profile</a>
      </Link>
      <Link href="/dashboard">
        <a>Dashboard</a>
      </Link>
      <Link href="/users">
        <a>Users</a>
      </Link>
      <Link href="/users/1">
        <a>Single User</a>
      </Link>
    </nav>
  )
}

• Add the following components:

// Layout.tsx

import Head from 'next/head'
import { LayoutProps } from '@/types/Components'
import { Nav } from '../ui/Nav'

export function Layout({ children, title }: LayoutProps) {
  return (
    <>
      <Head>
        <title>NextShield | {title}</title>
        <meta name="description" content="NextShield Example with Firebase" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <Nav />
      <div className="center">
        <main>{children}</main>
      </div>
    </>
  )
}

// Loading.tsx

import { BreedingRhombusSpinner } from 'react-epic-spinners'

export function Loading() {
  return <BreedingRhombusSpinner color="#00d1ff" className="loading" />
}

And finally the NextShield setup.

NextShield Setup.

In Shield.tsx file import the useRouter, the Loading.tsx and next-shield:

import { useRouter } from 'next/router'
import { NextShield, NextShieldProps } from 'next-shield'

import { Children } from '@/types/Components'
import { Loading } from './Loading'

export function Shield({ children }: Children) {
  const router = useRouter()



  return <>{children}</>
}

Just after the router create an object implementing the NextShieldProps called shieldProps:

const shieldProps: NextShieldProps = {}

You need to pass some generics to the type, the first one is an array of the private routes of your application, and the second one is an array with the public routes:

const shieldProps: NextShieldProps<
    ['/profile', '/dashboard', '/users', '/users/[id]'],
    ['/', '/login']
  > = {}

Then you need to pass the following props:

Router.

⇆ Instance of your router.

isAuth.

🔑 This value must be provided by the state of your app. Indicates if the user is authenticated or not.

isLoading.

⏳ This value must be provided by the state of your app. Indicates if the user's data is already available or not.

privateRoutes.

🚧 🚧 🚧 Array of private routes. These are only accessible when the user is authenticated.

publicRoutes.

👀 👀 👀 Array of public routes. These are only accessible when the user is NOT authenticated.

hybridRoutes.

🚦🚦🚦 Array of hybrid routes. These are always accessible; doesn't matter the auth state.

loginRoute.

📋 Login page. Must be a public route.

accessRoute.

🚧 Route where your user is going to access after login. Must be a private route.

LoadingComponent.

🌀 React Component which is going to appear when isLoading equals to true.

These are going to be the values, for this example:

const shieldProps: NextShieldProps<
    ['/profile', '/dashboard', '/users', '/users/[id]'],
    ['/', '/login']
  > = {
    router,
    isAuth: false,
    isLoading: false,
    privateRoutes: ['/profile', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/login'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/login',
    accessRoute: '/profile'
    LoadingComponent: <Loading />,
  }

Protect the app with NextShield.

Go to the _app.tsx file and wrap it with the Shield component:

import type { AppProps } from 'next/app'

import { Shield } from '@/components/routes/Shield'

import '@/styles/globals.css'

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Shield>
      <Component {...pageProps} />
    </Shield>
  )
}

Create the routes.

Create the following routes:

And write in each of them the following content:

import { Layout } from '@/components/routes/Layout'

export default function PageName() {
  return (
    <Layout title="PageName">
      <h1>PageName</h1>
    </Layout>
  )
}

By now you must have something like this:

As you can see, you can only access the public & hybrid routes, your private routes are completely protected, Even if you see your history the private routes won't appear:

Now you can play and set isAuth: true, you immediately won't be able to access the public routes.

Add RBAC.

Fine, you just got a simple example with auth users, now let's add something more interesting.

To add RBAC you need to pass the prop called RBAC as an object with the following configuration:

RBAC: {
      ADMIN: {
        grantedRoutes: ['/dashboard', '/profile', '/users', '/users/[id]'],
        accessRoute: '/dashboard',
      },
      EMPLOYEE: {
        grantedRoutes: ['/profile', '/dashboard'],
        accessRoute: '/profile',
      },
},

As you can see you define the roles of your app in the object keys, and inside you must define the grantedRoutes which is an array with the routes that are going to be accessible for that role, also you must define the accessRoute inside of this object and remove it from outside.

After that, you must pass the prop called userRole, which is the role of the current auth user, this must match with the object keys in RBAC, also this prop needs to be undefined when isAuth is false and defined when is true.

userRole: 'ADMIN', // Must be undefined when isAuth is false & defined when is true

The end result should look like this:

const shieldProps: NextShieldProps<
    ['/profile', '/dashboard', '/users', '/users/[id]'],
    ['/', '/login']
  > = {
    router,
    isAuth: true,
    isLoading: false,
    privateRoutes: ['/profile', '/dashboard', '/users', '/users/[id]'],
    publicRoutes: ['/', '/login'],
    hybridRoutes: ['/pricing'],
    loginRoute: '/login',
    LoadingComponent: <Loading />,
    RBAC: {
      ADMIN: {
        grantedRoutes: ['/dashboard', '/profile', '/users', '/users/[id]'],
        accessRoute: '/dashboard',
      },
      EMPLOYEE: {
        grantedRoutes: ['/profile', '/dashboard'],
        accessRoute: '/profile',
      },
    },
    userRole: 'ADMIN', // Must be undefined when isAuth is false & defined when is true
  }

And that's it! You will get the same behavior as before:

• Unable to access ungranted routes.
• No trace on your history.
• 0 flashy content, the LoadingComponent will always intercept the request before showing the page or redirecting the user.
• Configure everything in one place.

Next Steps.

1. Read the docs.
2. See the complete example on the repo (main branch)
3. Use it with your preferred auth provider.
4. Use ComponentShield to get more control of what is displayed on the screen.
5. Wait for the following Examples!

• Next.js
• Smtp.js
• Chakra UI
• React Hook Form

Also you can see the finished project here: GitHub Repo

Create the project.

As I already said you can use any react framework or bundler (vite, webpack, etc.) to do this, in my case I'm going to create a Next.js project.

 npx create-next-app --ts mail-template

Adding dependencies.

These dependencies are entirely optional, you can use your preferred packages.

• Install Chakra UI:

npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

Change your _app.tsx page to this:

import { ChakraProvider } from "@chakra-ui/react"

export default function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

• Install React Hook Form:

  npm i react-hook-form
  

Creating the template.

The template is nothing else but a React component, that's it, there is no magic, so let's create a directory called email at the root of our project, inside there create a file called EmailTemplate.tsx.

Define the props

On the root of our project create a directory called types and create a file called Email.ts inside of it:

In my case, I'm only going to support the following props, but you can define what you want based on your needs:

Add the markup

This step is complete ought to you, create a different markup if you needed but for this example, I'm going to use this:

import { EmailData } from '@/types/Email'

export function EmailTemplate({ subject, name, email, message }: EmailData) {
  return (
    <body>
      <section
        style={{
          backgroundColor: '#1a202c',
          color: '#ffffff',
          padding: '2rem',
        }}
      >
        <h1 style={{ textAlign: 'center', textTransform: 'capitalize', marginTop: 0 }}>
          {subject}
        </h1>
        <h3>
          Name: <span style={{ color: '#81e6d9' }}>{name}</span>
        </h3>
        <h3>
          Email:{' '}
          <a href={`mailto:${email}`} style={{ color: '#81e6d9' }}>
            {email}
          </a>
        </h3>

        <article
          style={{
            backgroundColor: '#308c7a4c',
            color: '#81e6d9',
            borderRadius: '0.5rem',
            padding: '1rem',
          }}
        >
          <h3 style={{ margin: 0 }}>Message:</h3>
          <p style={{ margin: 0, fontSize: '1rem' }}>{message}</p>
        </article>
      </section>
    </body>
  )
}

As you can see I'm using inline styles, Why? This is because you need your styles already embedded on your markup, if you try to use a CSS file instead your styles won't be applied.

Configuring SMTP.js

Before we continue with the form component, we need to configure SMTP.js.

SMTP.js is a completely free solution to send emails from the frontend, but there is a caveat to consider, the maintainers have absolutely 0 spam tolerance, so you need to apply some measures before launching an app to production.

You need an SMTP server, if you don't have one, you can use your Gmail account, but you need to enable your account for "less secure apps".

Now you need to go to the SMTP.js website and click on:

After that, you need to write your SMTP credentials, (if you are using Gmail, you can use the same exact values below).

This will generate a token that we need to save on a .env.local file at the root of our project, create a variable, and paste the token there, also create another variable to store your email.

NEXT_PUBLIC_EMAIL_TOKEN="secret token"
NEXT_PUBLIC_EMAIL="my@email.com"

Install SMTP.js SDK

Now click download in SMTP.js website:

And save the file inside the email directory that we created with a .ts extension:

Open the file and add on line 2 the comment // @ts-ignore, and replace var with export let:

Build the form.

As you may be already inferred, this is a simple form, 4 text fields, nothing special, so the following is the implementation of this simple form but with react-hook-form & Chakra UI.

So create the file under the directory components/forms/SendMail.tsx:

And add the code:

import { useCallback } from 'react'
import { renderToStaticMarkup } from 'react-dom/server'
import { Box, Center, Heading, VStack } from '@chakra-ui/layout'
import { FormControl, FormErrorMessage } from '@chakra-ui/form-control'
import { Input } from '@chakra-ui/input'
import { Textarea } from '@chakra-ui/textarea'
import { Button } from '@chakra-ui/button'
import { useToast } from '@chakra-ui/toast'
import { EmailIcon } from '@chakra-ui/icons'
import { SubmitHandler, useForm } from 'react-hook-form'

import type { EmailData } from '@/types/Email'
import { EmailTemplate } from '@/email/EmailTemplate'
import { Email } from '@/email/smtp'

export function SendMailForm() {
  const toast = useToast()
  const {
    handleSubmit,
    register,
    reset,
    formState: { errors, isSubmitting },
  } = useForm<EmailData>({ mode: 'onBlur' })

  const sendMail: SubmitHandler<EmailData> = useCallback(
    async data => {
      try {
        await Email.send({
          SecureToken: process.env.NEXT_PUBLIC_EMAIL_TOKEN,
          To: data.email,
          From: process.env.NEXT_PUBLIC_EMAIL,
          Subject: data.subject,
          Body: renderToStaticMarkup(<EmailTemplate {...data} />),
        })

        toast({
          title: 'Mail successfully sent',
          description: `The mail was sent to: ${data.email}`,
          status: 'success',
          position: 'top',
          duration: 5000,
          isClosable: true,
        })
      } catch (error) {
        console.error(error)
      } finally {
        reset()
      }
    },
    [reset, toast]
  )

  return (
    <Center h="100vh">
      <VStack spacing={7} align="stretch">
        <Heading as="h1" alignSelf="center">
          Send mail with SMTP.js
        </Heading>
        <Box maxW="lg" p="5" borderWidth="1px" borderRadius="lg" overflow="hidden">
          <form onSubmit={handleSubmit(sendMail)}>
            <VStack spacing={7} align="stretch">
              <FormControl isInvalid={errors.subject as boolean | undefined}>
                <Input
                  type="text"
                  id="subject"
                  placeholder="Subject"
                  {...register('subject', {
                    required: 'The subject is required',
                    minLength: { value: 4, message: 'Minimum length should be 4' },
                  })}
                />
                <FormErrorMessage>{errors.subject?.message}</FormErrorMessage>
              </FormControl>

              <FormControl isInvalid={errors.name as boolean | undefined}>
                <Input
                  type="text"
                  id="name"
                  placeholder="Name"
                  {...register('name', {
                    required: 'The name is required',
                    minLength: { value: 4, message: 'Minimum length should be 4' },
                  })}
                />
                <FormErrorMessage>{errors.name?.message}</FormErrorMessage>
              </FormControl>

              <FormControl isInvalid={errors.email as boolean | undefined}>
                <Input
                  type="email"
                  id="email"
                  placeholder="Email"
                  {...register('email', {
                    required: 'The email is required',
                    pattern: { value: /^\S+@\S+$/i, message: 'Write a valid email' },
                  })}
                />
                <FormErrorMessage>{errors.email?.message}</FormErrorMessage>
              </FormControl>

              <FormControl isInvalid={errors.message as boolean | undefined}>
                <Textarea
                  id="message"
                  placeholder="Write your message"
                  {...register('message', {
                    required: 'The message is required',
                    minLength: { value: 10, message: 'Minimum length should be 10' },
                  })}
                />
                <FormErrorMessage>{errors.message?.message}</FormErrorMessage>
              </FormControl>

              <Button
                type="submit"
                colorScheme="teal"
                size="md"
                loadingText="Submitting"
                isFullWidth={true}
                isLoading={isSubmitting}
                leftIcon={<EmailIcon />}
              >
                Send
              </Button>
            </VStack>
          </form>
        </Box>
      </VStack>
    </Center>
  )
}

Explanation.

Basically we are using SMTP.js SDK inside the sendMail function:

Email.send({
          SecureToken: process.env.NEXT_PUBLIC_EMAIL_TOKEN,
          To: data.email,
          From: process.env.NEXT_PUBLIC_EMAIL,
          Subject: data.subject,
          Body: renderToStaticMarkup(<EmailTemplate {...data} />),
 })

We are passing our secret token, email, and the subject, but the really important thing is in the Body:

renderToStaticMarkup(<EmailTemplate {...data} />)

renderToStaticMarkup is being imported from react-dom/server, this function receives the component which is the Email template that we did and returns a simple string with that markup as the content, that's when the email template is being created. Basically, what we did instead of writing a template string by ourselves, we created a simple React component and transpile it to a string with the tools that React already gives us by default.

To end this tutorial, we only need to import our form to the index page:

import Head from 'next/head'
import { SendMailForm } from '@/components/forms/SendMail'

export default function Home() {
  return (
    <>
      <Head>
        <title>Mail Sender</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <SendMailForm />
    </>
  )
}

Fill the form:

And check your inbox :D

In this post, I'm going to show you how to generate the build for Windows and create an installer for your end-user to make his installation process easy as possible.

What do you need before starting?

You only need two things installed in your system:

• Flutter
• Visual Studio 2019 with the “Desktop development with C++” workload installed, including all of its default components
• InnoSetup

The installation of Flutter and Visual Studio won't be explained because it's beyond the scope of this post, but I'll show you the installation of InnoSetup because we are going to create the installer with it.

InnoSetup Installation

1. First access the InnoSetup's website.

2. Then find this section and select a link in the Download Sites column:

3. Execute the innosetup-x.y.z.exe file, as you can see is the classic installation process:

Congrats! You have InnoSetup installed! 🥳

Creating the App

First, you need to enable the desktop environment in flutter by writing the following in PowerShell:

PS > flutter config --enable-windows-desktop

After that you can check the connected devices by executing flutter devices, you should see Windows (desktop) in the list:

PS > flutter devices
1 connected device:

Windows (desktop) • windows • windows-x64 • Microsoft Windows [Version 10.0.18362.1082]
...

If you have problems you can execute flutter doctor to see what's wrong, but you should see something like this:

PS > flutter doctor                                                                     
Doctor summary (to see all details, run flutter doctor -v):                                           
[√] Flutter (Channel beta, 1.27.0-1.0.pre, on Microsoft Windows [Version 10.0.19042.782], locale en-AU)
[√] Android toolchain - develop for Android devices (Android SDK version 30.0.3)                      
[√] Chrome - develop for the web                                                                      
[√] Visual Studio - develop for Windows (Visual Studio Community 2019 16.7.7)                         
[√] Android Studio (version 4.1.0)                                                                    
[√] VS Code (version 1.51.1)                                                                          
[√] Connected device (3 available)

If everything is ok, you can create a new project:

PS > flutter create windowsapp

Then go to the directory:

PS > cd windowsapp

And execute the app 🤩:

PS > flutter run -d windows

Great you are running a flutter app on Windows 🥳🎊🎉!!!

Build a Release App

As easy as running a single command 🥰:

PS > flutter build windows

The build is located in build\windows\runner\Release\:

Distributing the App

Now comes the interesting part and the hardest one, this is because you need to put some .dll files manually (🤮) and create your own installer.

So, you need to place 3 .dll files in the build folder, which are:

• msvcp140.dll
• vcruntime140.dll
• vcruntime140_1.dll

You must find them in the directory C:\Windows\System32. After you place these 3 files your build directory must look like this:

Creating the Installer

• Create a folder called installer inside the build folder.
• Open InnoSetup and click the first button:

• Then click on next:

• Then write your data and click next:

• You can change the folder settings as you wish, then click on next:

• This is the most important step, you have to click the Browse... button and select the .exe file, then click the Add Folder... button and select the Release folder (build\windows\runner\Release\) which is the build folder, finally it will appear a message saying "Should files in subfolders also be included?" you must click Yes and then click on next:

• Depending on your needs you should disable this section:

• You can customize this section also:

• Here you can attach your license and some other information:

• Then you can choose the installation method:

• Select the languages that you need for your installer:

• Select the installer folder that we created. and the name of the file, you can add a custom icon and password:

• Click next:

• Finally, click Finish and Yes

It will also ask you if you want to save the script, you can choose no if you want.

Installing Our App 🙂

Finally, after a few seconds, you will see the installer in the installer folder:

Open the installer and you'll see a classic installation process, you just have to click next until is installed.

And BOOM 🤯, you got a successful installation of a Flutter App on Windows 🥰

Hope you enjoyed this tutorial, see you next time 🤗

In this post, we will set our development environment with PHP, Laravel, MariaDB/MySQL, and Valet Linux; yeah, the exclusive macOS development tool working on Linux ;D.

Install MariaDB

To install MariaDB, open the terminal, and type the following command:

sudo apt install mariadb-server mariadb-client

After the installation concludes, test the following commands in that specific order to check if the installation was successful:

sudo systemctl stop mariadb.service
sudo systemctl start mariadb.service
sudo systemctl enable mariadb.service

After verifying the installation was successful, we need to run the mysql_secure_installation, to set MariaDB correctly in our development environment:

sudo mysql_secure_installation

After you execute the command, please answer the following questions:

• Enter current password for root (enter for none): Just press enter
• Set root password? [Y/n]: Y
• New password: Write a secure password
• Re-enter new password: Repeat the password
• Remove anonymous users? [Y/n]: Y
• Disallow root login remotely? [Y/n]: Y
• Remove test database and access to it? [Y/n]: Y
• Reload privilege tables now? [Y/n]: Y

Restart MariaDB's service:

sudo systemctl restart mariadb.service

Then, access to MariaDB through the terminal:

sudo mariadb -u root -p

Or

sudo mysql -u root -p

Remember that MariaDB is fully compatible with MySQL ;).

We need to write the password that we defined in the mysql_secure_installation process in the following SQL statement. This also helps to access MariaDB without sudo on the terminal:

GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED BY "your_password";

Now exit from MariaDB by pressing: Ctrl+C on the terminal.

Install PHP on Linux

This is very straight; forward we only need to run the following command:

sudo apt install php libapache2-mod-php php-common php-mbstring php-xmlrpc php-soap php-gd php-xml php-mysql php-cli php-mcrypt php-zip php-curl php-sqlite3 php-pgsql

And then open php.ini file to make some adjustments:

sudo nano /etc/php/7.X/apache2/php.ini

Modify the following variables:

memory_limit = 256M
upload_max_filesize = 64M
cgi.fix_pathinfo=0

We save the changes by pressing Ctrl+O and exit with Ctrl+X.

Install Laravel on Linux

We need composer installed in our system to do that, we can install it with:

sudo apt install composer

And now install Laravel:

composer global require laravel/installer

Now we need to add Laravel in our $PATH variable, to make "laravel" a recognizable command:

sudo nano .bashrc

If you are using zsh:

sudo nano .zshrc

Scroll down to the last line of the file and add the following:

export PATH="$HOME/.config/composer/vendor/bin:$PATH"

We save the changes by pressing Ctrl+O and exit with Ctrl+X.

And to force our shell to read the changes, execute:

source .bashrc

If you are using zsh:

source .zshrc

Now we can create a Laravel app:

laravel new laravel-app

If you want to use Laravel 7, try with the following commands and ensure that the PHP version you installed is PHP 7 and not PHP 8:

composer create-project laravel/laravel=^7 laravel-app --prefer-dist

If it does not work try replacing the ^ with >:

composer create-project laravel/laravel=>7 laravel-app --prefer-dist

It should create a Laravel app without problems.

Install Valet Linux

Finally, execute:

composer global require cpriego/valet-linux

If it throws an error, please execute:

sudo apt install php-curl

Try again and now it should work.

Now execute the installation process:

valet install

This also could throw an error, if that's the case, please force the shell to read the changes as we did before:

source .bashrc

If you are using zsh:

sudo nano .zshrc

We need to ensure that we update our $PATH environment variable correctly on the previous steps.

Now valet should throw an error about missing dependencies, to solve that we simply run:

sudo apt-get install network-manager libnss3-tools jq xsel

Now it should install valet correctly:

valet install

But if you have another error related with nginx, you need to stop the service that is running in the same port as nginx, if it's apache who is provoking this problem you can simply stop the apache's service:

sudo systemctl stop apache2.service

And try again:

valet install

To verify everything is ok, run:

ping valet.test

And after a few seconds it should say something like this:

X packets transmited, X received...

If that's the case, congrats! you successfully installed Valet Linux!

Now we need to set the directory where we are going to create Laravel or PHP projects:

cd directory/where/you/are/going/to/work

And execute:

valet park

Now create a folder called: phpinfo, inside the create a file called index.php and in the file, we can write something to check its working:

<?php echo phpinfo();

And finally, we write the following URL in our browser:

http://phpinfo.test/index.php

It should display info about PHP without errors.

You can custom the domain if you don't like .test with:

valet domain dev

And now to get access you need to change your current URL with the following: http://phpinfo.dev/index.php

And that's it, hope you enjoy it, if you want to see how to do it in fedora and manjaro, please comment it :D.