Forem: Eelco Wiersma

Stop Wrestling with React Icons - Meet Iconx: Your New Icon Workflow

Eelco Wiersma — Wed, 26 Nov 2025 20:27:24 +0000

The Icon Problem We've All Faced

Picture this: You're building a React app, and you need icons. Simple enough, right? Wrong.

You start with react-icons, and suddenly your bundle size balloons to 2MB+. You switch to icon fonts, but they feel like using a fax machine in 2025. You try Iconify's web components, but oops—your app breaks offline. And don't even get me started on manually copying SVGs from different icon libraries and trying to maintain them. 🤯

Enter Iconx: Icons the Way They Should Be

Today, I want to introduce you to Iconx—a CLI tool that fundamentally changes how we work with icons in React. Built by the team at Saas UI, it takes inspiration from the shadcn/ui philosophy: generate the code you own and control.

But here's the kicker: instead of being limited to a single icon set, you get access to 200,000+ icons from 150+ icon libraries. All type-safe. All tree-shakeable. All yours.

Why Iconx Exists (And Why You Should Care)

Let me break down the problems with current solutions:

The Bundle Size and Performance Problem: Libraries like react-icons ship entire icon sets. Even with tree-shaking, you're looking at significant overhead. Next.js apps especially suffer from this.

The Network Dependency Problem: CDN-based solutions like Iconify's web components are great... until you're on a plane, train, or just have spotty internet. Your icons shouldn't depend on network availability.

The Type Safety Problem: Copy-pasting SVGs? No TypeScript support. Icon fonts? Definitely no TypeScript support. Your IDE can't help you when things go wrong.

The Maintenance Problem: Managing individual SVG files or sprites becomes a nightmare as your app grows. Who's keeping track of which icons are actually used?

The Iconx Way: Best of All Worlds

Iconx solves these problems elegantly:

# Initialize your icon setup
npx iconx init

# Add only the icons you need
npx iconx add --set lucide home user settings

# Or use aliases for better naming
npx iconx add house:home cog:settings user:profile

And then in your React code:

import { HomeIcon } from './components/icons/home-icon'
import { SettingsIcon } from './components/icons/settings-icon'

function Navigation() {
  return (
    <nav>
      <HomeIcon size="24px" className="text-blue-500" />
      <SettingsIcon size="1.5rem" />
    </nav>
  )
}

What Makes Iconx Special?

1. You Own Your Icons

Every icon becomes a React component in your codebase. No external dependencies, no network requests, no surprises. Each component is self-contained with proper TypeScript interfaces:

export interface HomeIconProps extends React.SVGProps<SVGSVGElement> {
  size?: number | string
}

2. Access to the Entire Iconify Ecosystem

Want Lucide icons? Got it. Need Font Awesome? No problem. Prefer Heroicons? They're all there. You can mix and match from:

Lucide (lucide)
Heroicons (heroicons)
Tabler Icons (tabler)
Phosphor (phosphor)
Material Design (mdi)
Font Awesome (fa-solid, fa-regular, fa-brands)
...and 140+ more sets!

3. Perfect for Modern React

✅ RSC Compatible: Works seamlessly with React Server Components
✅ Tree-Shaking Perfection: Only the icons you import end up in your bundle
✅ TypeScript First: Full type safety and IDE autocomplete
✅ Offline First: Your icons work everywhere, always

4. Smart Aliasing

Don't like the original icon names? Create your own:

# Rename icons to match your design system
npx iconx add magnifying-glass:search x-mark:close

The Developer Experience You Deserve

One of my favorite aspects is how Iconx respects your workflow. It doesn't force a specific structure on you—configure the output directory, set default icon sizes, choose your preferred icon set. The generated components are clean, readable, and include helpful JSDoc comments with attribution and licensing info.

/**
 * home
 * Lucide
 * @url https://icon-sets.iconify.design/lucide
 * @license MIT
 * @version 1.0.0
 */
export const HomeIcon: React.FC<HomeIconProps> = ({ size, ...props }) => {
  // Clean, optimized SVG implementation
}

When Should You Use Iconx?

Iconx shines when:

You want the best balance between DX, performance, and bundle size
You're tired of wrestling with icon library limitations
You want to use icons from multiple libraries in one project
You believe in owning your dependencies

Getting Started is Ridiculously Easy

# Install icons.json (optional)
npx iconx init

# Start adding icons
npx iconx add --set lucide home user settings cart

That's it. No complex configuration, no webpack plugins, no build tool magic. Just icons that work.

The Bottom Line

By generating the actual source code instead of heavy libraries, it gives you the best of all worlds: performance, type safety, ease of use, and access to a massive icon ecosystem.

It's built on the same philosophy that made shadcn/ui so popular: give developers the code, not the library.

If you're tired of making compromises with your icon workflow, give Iconx a try. Your bundle size (and your future self) will thank you.

Disclamer

There are definitely downsides to using SVG-in-JS, however we feel like the benefits
outweigh the cons when building React apps and only use a dozen of icons on any
screen. If you're building a high traffic, mobile website you should definitely consider following Kurt's advice.

Ready to revolutionize your icon workflow? Check out the full documentation and start using Iconx today.

Have questions or want to share your experience? Drop a comment below! I'd love to hear how you're currently handling icons in your React projects and whether Iconx solves your pain points.

What's your biggest frustration with React icon libraries? Let me know in the comments! 👇

Next.js createPage helper with loader pattern

Eelco Wiersma — Wed, 28 Aug 2024 16:02:29 +0000

For the last two years I've been using a createPage helper with Next.js that
allows you to re-use some common features, like fetching data, checking roles or feature flags, etc.
This idea was originally posted by Rado Stankov and I've been using it ever since.

With the release of the app router in Next.js 13 I've been looking for a way to improve this pattern
and make better use of RSC (React Server Components), but didn't find a setup yet that I was fully happy with.

Earlier this week I came across a tweet from @matt_stobbs that showed the new
defineRoute function that will be introduced in React Router (and Remix) when it dawned on me that I could use this
to improve my createPage helper.

How it works

Here's an example how the new createPage helper is used in the Saas UI Pro starterkit.

import { notFound } from 'next/navigation'
import { z } from 'zod'

import { DashboardPage } from '#features/workspaces/dashboard'
import { createPage } from '#lib/create-page'
import { api } from '#lib/trpc/rsc.js'

const { Page, generateMetaData } = createPage({
  params: z.object({
    workspace: z.string(),
  }),
  searchParams: ['test'],
  loader: async ({ params }) => {
    const workspace = await api.workspaces.bySlug({
      slug: params.workspace,
    })

    if (!workspace) {
      notFound()
    }

    return {
      workspace,
    }
  },
  metadata: async ({ data }) => ({
    title: `Dashboard - ${data.workspace.name}`,
  }),
  component: ({ params, searchParams, data }) => (
    <DashboardPage
      params={params}
      searchParams={searchParams}
      workspace={data.workspace}
    />
  ),
})

export { generateMetaData }

export default Page

So what's happening here?

The createPage function is a factory function that returns a Page component and metadata or generateMetaData that can be exported from an app router page.tsx.

We can define params and searchParams using Zod schemas (or an array with the param names ['workspace']).
These then become available in the loader function that is called server-side to fetch the data for the metadata and page component.

In this example we're fetchin data from a tRPC procedure, but this could be any async function that returns the data needed for the page.
The return value of the loader function is then inferred by the metadata, and component handlers.

The component returned by the createPage is a React Server Component that wraps the DashboardPage component, which can be a regular client component, or another RSC.

Now we no longer have to import and move around types, params and searchParams are validated, and established a common pattern for fetching initial data for our metadata and page components.

Extending the helper

You can easily extend this helper with extra functionality, like role access.

const { Page, generateMetaData } = createPage({
  roles: ['admin'],
  component: ({ params, searchParams, data }) => (
    <AdminPage params={params} searchParams={searchParams} data={data} />
  ),
})

Source code

You can find the source code in this gist, there are still a few details I'm not certain about.

Use safeParse for the params and searchParams?
Should the component be wrapped with Suspense?
Can we hydrate the data returned from the loader function easily to React Query.
cache the loader function?
Turn this into a library?

Please do leave a comment if you have idea's, suggestions or other feedback.

Thanks for reading :)

Building a multi-tenant B2B SaaS with Vite and Tanstack Router & Query - Part 1: The boilerplate

Eelco Wiersma — Thu, 22 Feb 2024 20:52:40 +0000

Introduction

React Server Components (RSC) are the new craze, but what if I told you SPA's (Single-page-app) are here to stay, especially for B2B applications.

This article is the first in a series where we'll build a multi-tenant B2B SaaS. We'll go over the basics of setting up Vite with Tanstack Router and a basic UI with authentication and building an API with Supabase.

Vite is a blazing fast build tool, built on modern standards like ESM and is highly extensible.
Tanstack Router is a powerful new router for React with support for file based routing, is fully type-safe and has a great developer experience.
We'll use Chakra UI with the Saas UI design system for styling.

This stack will be fully type-safe from backend, to routing, and styling. There's no magic, easy to reason about and just a pleasure to work with.

Add the end of this article you will have a basic multi-tenant UI boilerplate to build upon.
You can get the full source code of this project on Github.

Setting up Vite

First things first, let's set up Vite. We'll start by creating a new project with Vite.

npm create vite@latest my-saas -- --template react-ts

We'll also install the dependencies for Tanstack Router.

cd my-saas
npm i @tanstack/react-router @tanstack/router-devtools @tanstack/router-vite-plugin

Configure the Vite plugin

Edit the vite.config.ts file and add the following configuration for the router plugin.
The router plugin will handle generating the route tree and types for us.

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), TanStackRouterVite()],
})

Setting up the router

Now that we have the router plugin set up, we can start creating our routes. Create a new file called __root.tsx in the src/routes folder.

import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

export const Route = createRootRoute({
  component: () => (
    <>
      <div>
        <Link to="/">
          Home
        </Link>
      </div>
      <hr />
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

Create the index route in routes/index.tsx.

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
})

function Index() {
  return (
    <div>
      <h3>Welcome Home!</h3>
    </div>
  )
}

The Router plugin will generate the route tree for us based on the file structure. The __root.tsx file is the root of our route tree and will be used to render the main layout of our application.

We can now initialize the router and setup the context provider. Create a new file called provider.tsx in the src/context folder.

import { RouterProvider, createRouter, Link } from '@tanstack/react-router'

import { routeTree } from '../routeTree.gen'

// Set up a Router instance
const router = createRouter({
  routeTree,
})

// Register things for typesafety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

export const Provider = () => {
  return (
    <RouterProvider router={router} />
  )
}

Add the provider to the main.tsx file.

import React from 'react'
import ReactDOM from 'react-dom/client'
import { Provider } from './context/provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Provider />
  </React.StrictMode>
)

Great, we now have a basic setup for the router. Run the dev server with npm run dev and open the browser to see the basic layout with the home link and welcome message.

Styling

To make our application look great, we'll use Chakra UI with the Saas UI design system. First, we'll install the dependencies.

npm i @saas-ui/react @chakra-ui/react @chakra-ui/next-js @emotion/react @emotion/styled framer-motion

Then we need to add the SaasProvider to the context/provider.tsx file.

import { forwardRef } from "react";
import { SaasProvider } from "@saas-ui/react";
import {
  Link,
  LinkProps,
  RouterProvider,
  createRouter,
} from "@tanstack/react-router";

import { routeTree } from "../routeTree.gen";

// Set up a Router instance
const router = createRouter({
  routeTree,
});

// Register things for typesafety
declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

// This makes sure Saas UI components use our router
const LinkComponent = forwardRef<HTMLAnchorElement, Pick<LinkProps, "href">>(
  (props, ref) => {
    const { href, ...rest } = props;
    return <Link ref={ref} to={href} {...rest} />;
  }
);

export const Provider = () => {
  return (
    <SaasProvider linkComponent={LinkComponent}>
      <RouterProvider router={router} />
    </SaasProvider>
  );
};

Now we can start using the Chakra UI components in our application. Let's update the routes/index.tsx file to use the Saas UI components.

import { Box, Heading } from '@chakra-ui/react'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
})

function Index() {
  return (
    <Box p="8">
      <Heading as="h1" mb="4">
        Welcome Home!
      </Heading>
    </Box>
  )
}

The app should look much better already :)

Cleanup

We no longer need the App.tsx, App.css and index.css files that came with Vite, so we can remove them.

rm src/App.tsx src/App.css src/index.css

Setup React Query

Now that we have the basic layout and styling set up, we can add React Query for data fetching and mutations.

Tanstack router supports loaders, which are functions that can be used to fetch data before rendering the component. Loaders work great with Tanstack Query, which is a powerful data fetching library for React.
Let's set up Tanstack Query and create a simple loader to fetch some data.

npm i @tanstack/react-query @tanstack/react-query-devtools

After installing the dependencies, we need to add the QueryClientProvider to the context/provider.tsx file.

import { forwardRef } from 'react'
import { LinkProps, SaasProvider } from '@saas-ui/react'
import { RouterProvider, createRouter, Link } from '@tanstack/react-router'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

import { routeTree } from '../routeTree.gen'

const queryClient = new QueryClient()

// Set up a Router instance
const router = createRouter({
  routeTree,
  context: {
    queryClient,
  },
  defaultPreload: 'intent',
  // Since we're using React Query, we don't want loader calls to ever be stale
  // This will ensure that the loader is always called when the route is preloaded or visited
  defaultPreloadStaleTime: 0,
})

// Register things for typesafety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

// This makes sure Saas UI components use our router
const LinkComponent = forwardRef<HTMLAnchorElement, Pick<LinkProps, 'href'>>(
  (props, ref) => {
    const { href, ...rest } = props
    return <Link ref={ref} to={href} {...rest} />
  }
)

export const Provider = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <SaasProvider linkComponent={LinkComponent}>
        <RouterProvider router={router} />
      </SaasProvider>
    </QueryClientProvider>
  )
}

What's notable here is we're setting up a QueryClient and providing it to the QueryClientProvider. We're also passing the queryClient to the router context, so we can use it in our loaders.

Setting the defaultPreload to intent will ensure that data is preloaded when the user hovers or clicks a Link.

We also set defaultPreloadStaleTime to 0, which will ensure that the loader is always called when the route is preloaded or visited. This is because React Query will handle the caching and we don't want the loader calls to ever be stale.

Router context

To make sure the query client type is available in the router context, we need to add the type to the router.

Edit src/router/__root.tsx and change createRootRoute to createRootRouteWithContext.

import { QueryClient } from '@tanstack/react-query'
import {
  createRootRouteWithContext,
  Link,
  Outlet,
} from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
}>()({
  component: () => (
    <>
      <div>
        <Link to="/">Home</Link>
      </div>
      <hr />
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

Fetching data

Now we can create a simple loader to fetch some data. Create a new file called routes/profile.tsx in the src/routes folder.
We don't have an actual API to fetch data from, so we'll just return some dummy data for now.

import { createFileRoute } from '@tanstack/react-router'
import { useQuery, queryOptions } from '@tanstack/react-query'
import { Box, Heading } from '@chakra-ui/react'

const profileQueryOptions = queryOptions({
  queryKey: ['profile'],
  queryFn: () => {
    return {
      id: '1',
      name: 'John Doe',
    }
  },
})

export const Route = createFileRoute('/profile')({
  loader: ({ context: { queryClient } }) =>
    queryClient.ensureQueryData(profileQueryOptions),
  component: Data,
})

function Data() {
  const { data } = useSuspenseQuery(profileQueryOptions)

  return (
    <Box p="8">
      <Heading as="h1" mb="4">
        Profile
      </Heading>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </Box>
  )
}

Open the browser and navigate to the /profile route. You should see the dummy data displayed on the page.

Go ahead and delete this file again, we will create a proper API to fetch data from in the next article.

Adding layouts

Now that we have the basics out of the way, let's add some more advanced features. We'll start by adding layouts to our application.

We'll be creating a SidebarLayout for the main layout of our application. This will also need a couple of components.
To make our lives a bit easier and to keep our codebase clean, let's first create an import alias, so we don't need to use relative imports.

Import alias

Edit package.json and add the following to the imports field. This will use Node.js subpath imports feature, which is now also natively supported by Typescript.
The benefit of this is that's it's a native feature and doesn't need any bundler configuration or additional tooling.

{
  // ...
  "scripts": {
    // ...
  },
  "imports": {
    "#*": ["./src/*", "./src/*.ts", "./src/*.tsx"]
  }
  // ...
}

Sidebar component

Create a new file called sidebar.tsx in the src/components folder.

import { NavGroup, NavItem, Sidebar, SidebarSection } from '@saas-ui/react'
import { getRouteApi } from '@tanstack/react-router'

const route = getRouteApi('/_app/$workspace/')

export const AppSidebar = () => {
  const params = route.useParams()

  return (
    <Sidebar>
      <SidebarSection>
        <NavGroup>
          <NavItem href={`/${params.workspace}`}>Home</NavItem>
        </NavGroup>
      </SidebarSection>
    </Sidebar>
  )
}

The getRouteApi util is used to get the route API for the workspace route. This will allow us to get the workspace from the route params in a type-safe way.

Sidebar layout

Create a new file called sidebar-layout.tsx in the src/layouts folder.

import { AppShell } from '@saas-ui/react'

import { AppSidebar } from '#components/sidebar'

export const SidebarLayout: React.FC<React.PropsWithChildren> = (props) => {
  return (
    <AppShell height="$100vh" sidebar={<AppSidebar />}>
      {props.children}
    </AppShell>
  )
}

Layout route

Layout routes are a way to wrap a route with a layout. This is useful for creating a consistent layout for a group of routes.

Create a new file called _app.tsx in the src/routes folder.

import { Outlet, createFileRoute } from '@tanstack/react-router'

import { SidebarLayout } from '#layouts/sidebar-layout'

export const Route = createFileRoute('/_app')({
  component: AppLayout,
})

function AppLayout() {
  return (
    <SidebarLayout>
      <Outlet />
    </SidebarLayout>
  )
}

All routes that are children of the _app/* route will now be wrapped in the AppLayout.
Routes prefixed with _ are considered pathless, and will not be part of the final route path.

This will allow us to create different root layouts for the app, authentication screens and marketing pages.

Let's clean up the root layout that we created initially. Edit src/routes/__root.tsx and remove the Link and html elements.

import { QueryClient } from '@tanstack/react-query'
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
}>()({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

Workspace route

Since we're building a multi-tenant SaaS application we'll need a way to handle different workspaces.
We can do that using a dynamic route segments, or path parameters. Segments are prefixed with a $.

Create a new folder $workspace in /src/routes/_app and create a new file called index.tsx in that folder.

import { Center } from '@chakra-ui/react'
import { EmptyState } from '@saas-ui/react'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_app/$workspace/')({
  component: Home,
})

function Home() {
  return (
    <Center height="$100vh">
      <EmptyState
        variant="centered"
        title="Nothing here yet"
        description="Add routes and pages to get started"
      />
    </Center>
  )
}

Open the browser and navigate to http://localhost:5173/test. You should see the sidebar layout with an empty state displayed on the page.

Amazing work so far! When you go to http://localhost:5173, you'll notice we don't have navigation anymore, and there's no way to navigate to the workspace route.
In the next steps we'll add an onboarding screen that will allow users to create a workspace and navigate to it.

Onboarding

We'll create an onboarding screen that will allow users to create a workspace and navigate to it.
Note that we haven't added authentication yet, don't worry about that for now, we'll cover that in the next article.

For the onboarding screens we want to use a different layouts, without the sidebar.

Create a new file called fullscreen-layout.tsx in the src/layouts folder.
This layout can be used for features like onboarding, that allow users to focus on a single task.

import { AppShell } from '@saas-ui/react'

export const FullscreenLayout: React.FC<React.PropsWithChildren> = (props) => {
  return <AppShell height="$100vh">{props.children}</AppShell>
}

Create the _onboarding.tsx layout route in the src/routes folder.

import { Outlet, createFileRoute } from '@tanstack/react-router'

import { FullscreenLayout } from '#layouts/fullscreen-layout'

export const Route = createFileRoute('/_onboarding')({
  component: OnboardingLayout,
})

function OnboardingLayout() {
  return (
    <FullscreenLayout>
      <Outlet />
    </FullscreenLayout>
  )
}

And create the page route in src/routes/_onboarding/getting-started.tsx.

import { Center, Container, Heading } from '@chakra-ui/react'
import { Field, Form, FormLayout, SubmitButton } from '@saas-ui/react'
import { useMutation } from '@tanstack/react-query'
import { createFileRoute, useNavigate } from '@tanstack/react-router'
import { FormEvent } from 'react'

const slugify = (value: string) => {
  return value
    .trim()
    .toLocaleLowerCase()
    .replace(/[^\w\s-]/g, '')
    .replace(/[\s_-]+/g, '-')
    .replace(/^-+|-+$/g, '')
}

export const Route = createFileRoute('/_onboarding/getting-started')({
  component: GettingStarted,
})

interface OnboardingData {
  organization: string
  workspace: string
}

function GettingStarted() {
  const navigate = useNavigate()

  const submit = useMutation<unknown, Error, OnboardingData>({
    mutationFn: async (values) => {
      localStorage.setItem('workspace', values.workspace)
    },
    onSuccess: (data, variables) => {
      navigate({
        to: '/$workspace',
        params: { workspace: variables.workspace },
      })
    },
  })

  return (
    <Center height="$100vh">
      <Container maxW="container.sm">
        <Heading as="h2" size="lg" mb="4">
          Getting started
        </Heading>
        <Form
          onSubmit={(data) => submit.mutateAsync(data)}
          defaultValues={{
            organization: '',
            workspace: '',
          }}
        >
          {({ setValue }) => (
            <FormLayout>
              <Field
                label="Organization name"
                name="organization"
                onChange={(e: FormEvent<HTMLInputElement>) => {
                  const value = e.currentTarget.value
                  setValue('organization', value)
                  setValue('workspace', slugify(value))
                }}
              />
              <Field label="Workspace" name="workspace" />
              <SubmitButton>Continue</SubmitButton>
            </FormLayout>
          )}
        </Form>
      </Container>
    </Center>
  )
}

Ok, so what's going on here? We're using the useMutation hook from Tanstack Query to handle the form submission. When the form is submitted, we'll save the workspace to localStorage and navigate to the workspace route.

We're using Saas UI Form component that allows us to quickly created type-safe forms. It also has support for Zod, Yup and JsonSchema.

Whenever the organization value changes we automatically update the workspace value using the slugify function to pre-fill the workspace field.

The screen should look like this:

Try it out yourself at http://localhost:5173/getting-started.

Redirecting the user

When the user navigates to the root of the application, we want to redirect them to the workspace route if they have a workspace in localStorage, otherwise we want to redirect them to the onboarding screen.

Edit src/routes/index.tsx and add the following code.

import { Box, Heading } from '@chakra-ui/react'
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Index,
  beforeLoad: async () => {
    // We will add authentication here later
    const user = {
      id: '123',
      email: 'john.doe@acme.com',
    }

    if (!user) {
      return
    }

    const workspace = localStorage.getItem('workspace')

    const path = workspace ? `/${workspace}` : '/getting-started'

    throw redirect({
      to: path,
    })
  },
})

function Index() {
  return (
    <Box p="8">
      <Heading as="h1" mb="4">
        Welcome Home!
      </Heading>
    </Box>
  )
}

We're using the beforeLoad hook to check if the user has a workspace in localStorage. If they do, we'll redirect them to the workspace route, otherwise we'll redirect them to the onboarding screen.
If the user is not authenticated, we'll just return and show the home screen.

Now navigate to http://localhost:5173 and you should be redirected.

Conclusion

In this article, we've set up a basic multi-tenant B2B SaaS application boilerplate using Vite, Tanstack Router, Chakra UI and Saas UI.
We've also added React Query for data fetching and mutations, and created a simple onboarding screen.

In the next article, we'll add authentication (Supabase Auth), and a proper API to fetch data from.
I'm not sure yet what we're going to use for the API, we might use Supabase directly or use Hono, what do you think?

Resources

Building a multi-step onboarding flow in 5 minutes

Eelco Wiersma — Thu, 16 Jun 2022 15:24:10 +0000

In this post I will show you how easy it to build a multi-step onboarding flow with Saas UI.

Saas UI is a component library build on top of Chakra UI and contains a lot of components currently missing in Chakra UI as well as higher order components that help boost your productivity.

You typically find onboarding flows during or after signing up for a new product and can consist of a couple of steps to help you setup your new account.

The tech

The stack that we will be using:

Saas UI
Chakra UI
Next.js
React Hook Form (used internally by Saas UI)

The requirements

For this example we will be building a form with 3 steps. It should have a stepper to indicate in which step the user currently is, validation and it should work well on small screens.

Information

Here we will ask for some personal information as well as business information.

First name, last name, company, if a company name is entered, ask for the company size.

Create workspace

Workspace name and url

Invite team members

Be able to enter multiple email addresses.

1. Installation

I've prepared a starter repository to help you get started quickly. Get it from Github

git clone git@github.com:saas-js/saas-ui-nextjs-typescript.git

After closing let's install all dependencies.

yarn

Existing project

If you want to continue in an existing Next.js project you can run this to install all required dependencies.

yarn add @saas-ui/react @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6

2. Create the onboarding page

So first thing we need to do is create a page for the onboarding flow.

Create a new page; pages/onboarding.tsx

import { Box } from '@chakra-ui/react'

import { NextPage } from 'next'

const OnboardingPage : NextPage = () => {
  return (
    <Box>
      Onboarding
    </Box>
  )
}
export default OnboardingPage

Now open your browser and visit:

https://localhost:3000/onboarding

If everything went right, you should see Onboarding now. 👊

Now let's make the page look a bit better by adding a title and let's create the first form step.

import { Container, Heading, VStack } from '@chakra-ui/react'
import {
  Card,
  CardBody,
  Field,
  FormLayout,
  FormStep,
  NextButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px">
          <FormStep name="information">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field name="firstName" label="First name" />
                  <Field name="lastName" label="Last name" />
                  <NextButton />
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

Looks good already doesn't it? We now have a fully working multi step form. Try it out by entering some information and pressing complete. You should see the values in the console, ready to post to your backend. 🚀

StepForm (and Form) use React Hook Form internally to manage the form state, it allows you to build forms super fast without a lot of boilerplate.

Now let's add the rest of the fields and the other 2 steps to make it truly multi step.

import { ButtonGroup, Container, Heading, VStack } from '@chakra-ui/react'
import {
  Card,
  CardBody,
  Field,
  FormLayout,
  FormStep,
  NextButton,
  PrevButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px">
          <FormStep name="information">
            <Card>
              <CardBody>
                <FormLayout>
                  <FormLayout columns={2}>
                    <Field name="firstName" label="First name" />
                    <Field name="lastName" label="Last name" />
                  </FormLayout>
                  <Field name="company" label="Company name" />
                  <NextButton />
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="workspace">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field name="name" label="Workspace name" />
                  <Field name="url" label="Workspace url" />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="invite">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field
                    name="email"
                    label="Invite your teammembers"
                    help="Add multiple addresses by separating them with a comma (,)"
                    type="textarea"
                  />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

Awesome we can now move back and forth through our steps. When you complete the last step you should see all your field values being logged in the console. Sweet!

The next step is to add some validation, because we can complete all steps now without entering any information.

import { ButtonGroup, Container, Heading, VStack } from '@chakra-ui/react'
import {
  Card,
  CardBody,
  Field,
  FormLayout,
  FormStep,
  NextButton,
  PrevButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px" noValidate>
          <FormStep name="information">
            <Card>
              <CardBody>
                <FormLayout>
                  <FormLayout columns={2}>
                    <Field
                      name="firstName"
                      label="First name"
                      isRequired
                      rules={{ required: 'Please enter your first name.' }}
                    />
                    <Field
                      name="lastName"
                      label="Last name"
                      isRequired
                      rules={{ required: 'Please enter your last name.' }}
                    />
                  </FormLayout>
                  <Field name="company" label="Company name" />
                  <NextButton />
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="workspace">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field
                    name="name"
                    label="Workspace name"
                    isRequired
                    rules={{ required: 'Please enter a name ' }}
                  />
                  <Field
                    name="url"
                    label="Workspace url"
                    help="We will create one for you if you leave this empty."
                  />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="invite">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field
                    name="emails"
                    label="Invite your teammembers"
                    help="Add multiple addresses by separating them with a comma (,)"
                    type="textarea"
                  />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

That was easy! rules accepts all React Hook Form rules and the form also accepts schema resolvers, but more on this in another post.

Note that we added noValidate to the form, to disable the native browser validation messages.

Ok, so we want to ask a little bit more information when a company signed up. Let's add this now, we can simply do this with the DisplayIf component. We'll add a custom Select with the company size options.

import { ButtonGroup, Container, Heading, VStack } from '@chakra-ui/react'
import {
  Card,
  CardBody,
  DisplayIf,
  Field,
  FormLayout,
  FormStep,
  NextButton,
  PrevButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px" noValidate>
          <FormStep name="information">
            <Card>
              <CardBody>
                <FormLayout>
                  <FormLayout columns={2}>
                    <Field
                      name="firstName"
                      label="First name"
                      isRequired
                      rules={{ required: 'Please enter your first name.' }}
                    />
                    <Field
                      name="lastName"
                      label="Last name"
                      isRequired
                      rules={{ required: 'Please enter your last name.' }}
                    />
                  </FormLayout>
                  <Field name="company" label="Company name" />
                  <DisplayIf name="company">
                    <Field
                      name="companySize"
                      label="Company size"
                      placeholder="Select your company size"
                      type="select"
                      options={[
                        {
                          value: '1',
                          label: '1 to 5',
                        },
                        {
                          value: '5',
                          label: '5 to 20',
                        },
                        {
                          value: '20',
                          label: '20 or more',
                        },
                      ]}
                    />
                  </DisplayIf>
                  <NextButton />
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="workspace">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field
                    name="name"
                    label="Workspace name"
                    isRequired
                    rules={{ required: 'Please enter a name ' }}
                  />
                  <Field
                    name="url"
                    label="Workspace url"
                    help="We will create one for you if you leave this empty."
                  />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
          <FormStep name="invite">
            <Card>
              <CardBody>
                <FormLayout>
                  <Field
                    name="emails"
                    label="Invite your teammembers"
                    help="Add multiple addresses by separating them with a comma (,)"
                    type="textarea"
                  />
                  <ButtonGroup>
                    <NextButton />
                    <PrevButton />
                  </ButtonGroup>
                </FormLayout>
              </CardBody>
            </Card>
          </FormStep>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

Bam! Conditional fields without any difficult logic or if/else statements.

Now we still miss an important part, the Stepper, let's add this now. We can simply wrap the steps with the FormStepper component and add a title to the steps.

import { ButtonGroup, Container, Heading, VStack } from '@chakra-ui/react'
import {
  Card,
  CardBody,
  DisplayIf,
  Field,
  FormLayout,
  FormStep,
  FormStepper,
  NextButton,
  PrevButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px" noValidate>
          <FormStepper>
            <FormStep name="information" title="Information">
              <Card>
                <CardBody>
                  <FormLayout>
                    <FormLayout columns={2}>
                      <Field
                        name="firstName"
                        label="First name"
                        isRequired
                        rules={{ required: 'Please enter your first name.' }}
                      />
                      <Field
                        name="lastName"
                        label="Last name"
                        isRequired
                        rules={{ required: 'Please enter your last name.' }}
                      />
                    </FormLayout>
                    <Field name="company" label="Company name" />
                    <DisplayIf name="company">
                      <Field
                        name="companySize"
                        label="Company size"
                        placeholder="Select your company size"
                        type="select"
                        options={[
                          {
                            value: '1',
                            label: '1 to 5',
                          },
                          {
                            value: '5',
                            label: '5 to 20',
                          },
                          {
                            value: '20',
                            label: '20 or more',
                          },
                        ]}
                      />
                    </DisplayIf>
                    <NextButton />
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="workspace" title="Workspace">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="name"
                      label="Workspace name"
                      isRequired
                      rules={{ required: 'Please enter a name ' }}
                    />
                    <Field
                      name="url"
                      label="Workspace url"
                      help="We will create one for you if you leave this empty."
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="invite" title="Invite team">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="emails"
                      label="Invite your teammembers"
                      help="Add multiple addresses by separating them with a comma (,)"
                      type="textarea"
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
          </FormStepper>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

The last requirement we have is to make the form work well on small screens. Luckily the Stepper supports a vertical orientation, we can use this in combination with useBreakpointValue. We'll also make sure the first and last name is rendered under each other on mobile screens.

import {
  ButtonGroup,
  Container,
  Heading,
  useBreakpointValue,
  VStack,
} from '@chakra-ui/react'
import {
  Card,
  CardBody,
  DisplayIf,
  Field,
  FormLayout,
  FormStep,
  FormStepper,
  NextButton,
  PrevButton,
  StepForm,
} from '@saas-ui/react'

import { NextPage } from 'next'

const OnboardingPage: NextPage = () => {
  const onSubmit = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm onSubmit={onSubmit} width="420px" noValidate>
          <FormStepper
            orientation={useBreakpointValue({
              base: 'vertical',
              md: 'horizontal',
            })}
          >
            <FormStep name="information" title="Information">
              <Card>
                <CardBody>
                  <FormLayout>
                    <FormLayout columns={{ base: 1, md: 2 }}>
                      <Field
                        name="firstName"
                        label="First name"
                        isRequired
                        rules={{ required: 'Please enter your first name.' }}
                      />
                      <Field
                        name="lastName"
                        label="Last name"
                        isRequired
                        rules={{ required: 'Please enter your last name.' }}
                      />
                    </FormLayout>
                    <Field name="company" label="Company name" />
                    <DisplayIf name="company">
                      <Field
                        name="companySize"
                        label="Company size"
                        placeholder="Select your company size"
                        type="select"
                        options={[
                          {
                            value: '1',
                            label: '1 to 5',
                          },
                          {
                            value: '5',
                            label: '5 to 20',
                          },
                          {
                            value: '20',
                            label: '20 or more',
                          },
                        ]}
                      />
                    </DisplayIf>
                    <NextButton />
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="workspace" title="Workspace">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="name"
                      label="Workspace name"
                      isRequired
                      rules={{ required: 'Please enter a name ' }}
                    />
                    <Field
                      name="url"
                      label="Workspace url"
                      help="We will create one for you if you leave this empty."
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="invite" title="Invite team">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="emails"
                      label="Invite your teammembers"
                      help="Add multiple addresses by separating them with a comma (,)"
                      type="textarea"
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
          </FormStepper>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

Without a blink! 😎

Now we're almost ready, you probably have noticed the type warning in the onSubmit handler. Let's solve this by making the form typesafe.

Your form should something like this now.

import {
  ButtonGroup,
  Container,
  Heading,
  useBreakpointValue,
  VStack,
} from '@chakra-ui/react'
import {
  Card,
  CardBody,
  DisplayIf,
  Field,
  FormLayout,
  FormStep,
  FormStepper,
  NextButton,
  PrevButton,
  StepForm,
  SubmitHandler,
} from '@saas-ui/react'

import { NextPage } from 'next'

interface InformationInputs {
  firstName: string
  lastName: string
  company?: string
  companySize: string
}

interface WorkspaceInputs {
  name: string
  url?: string
}

interface InviteInputs {
  email?: string
}

type FormInputs = InformationInputs & WorkspaceInputs & InviteInputs

const OnboardingPage: NextPage = () => {
  const onSubmit: SubmitHandler<FormInputs> = async (data) => {
    console.log(data)
  }

  return (
    <Container maxW="container.xl" pt="20">
      <VStack spacing="8">
        <Heading size="lg" textAlign="center">
          Welcome to ACME Corp
        </Heading>

        <StepForm<FormInputs> onSubmit={onSubmit} width="420px" noValidate>
          <FormStepper
            orientation={useBreakpointValue({
              base: 'vertical',
              md: 'horizontal',
            })}
          >
            <FormStep name="information" title="Information">
              <Card>
                <CardBody>
                  <FormLayout>
                    <FormLayout columns={{ base: 1, md: 2 }}>
                      <Field
                        name="firstName"
                        label="First name"
                        isRequired
                        rules={{ required: 'Please enter your first name.' }}
                      />
                      <Field
                        name="lastName"
                        label="Last name"
                        isRequired
                        rules={{ required: 'Please enter your last name.' }}
                      />
                    </FormLayout>
                    <Field name="company" label="Company name" />
                    <DisplayIf name="company">
                      <Field
                        name="companySize"
                        label="Company size"
                        placeholder="Select your company size"
                        type="select"
                        options={[
                          {
                            value: '1',
                            label: '1 to 5',
                          },
                          {
                            value: '5',
                            label: '5 to 20',
                          },
                          {
                            value: '20',
                            label: '20 or more',
                          },
                        ]}
                      />
                    </DisplayIf>
                    <NextButton />
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="workspace" title="Workspace">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="name"
                      label="Workspace name"
                      isRequired
                      rules={{ required: 'Please enter a name ' }}
                    />
                    <Field
                      name="url"
                      label="Workspace url"
                      help="We will create one for you if you leave this empty."
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
            <FormStep name="invite" title="Invite team">
              <Card>
                <CardBody>
                  <FormLayout>
                    <Field
                      name="emails"
                      label="Invite your teammembers"
                      help="Add multiple addresses by separating them with a comma (,)"
                      type="textarea"
                    />
                    <ButtonGroup>
                      <NextButton />
                      <PrevButton />
                    </ButtonGroup>
                  </FormLayout>
                </CardBody>
              </Card>
            </FormStep>
          </FormStepper>
        </StepForm>
      </VStack>
    </Container>
  )
}
export default OnboardingPage

Great work! We got a fully working multi step form ready in just a few minutes.

You can find the fully working example here.

Now there is a lot more you can add, like hooking up the steps to the router. Adding schema validation and more advanced fields like the ArrayField to add individual email instead of a comma separated list.

Let me know what you think in the comments and what you would like to see more.

Happy coding! 🤓