Author at Infinum

Get Your Components in Order with React Project Structure

Ivica Batinić — Wed, 24 May 2023 11:21:32 +0000

Want to explore the rules and best practices for structuring React projects and unlock the full potential of your development process? Read on.

In the world of web development, a well-organized project structure is essential for the success and maintainability of any React application. At Infinum, we have developed a comprehensive stack that serves as the foundation for our projects. However, the principles and guidelines we follow can be applied universally to any React project.

Our stack includes powerful tools and libraries:

Next.js
TypeScript
Datx
JSON:API
SWR
Chakra UI
React Hook Form
React Testing Library and Jest for unit and integration tests
Storybook
I18Next
Plop Next.js Generators

Leveraging these technologies allows us to build robust and scalable applications.

To showcase the effectiveness of our React project structure, we maintain an example repository on GitHub. This repository serves as a practical reference and demonstrates how our project structure aligns with industry best practices.

In this blog post, we will dive into the key components of our React project structure, explaining how each tool and library contributes to the overall organization, maintainability, and efficiency of our React applications.

Whether you are using our stack or working with different technologies, the insights shared here will help you establish a solid foundation for your React projects.

Organizing components in React project structure

When it comes to organizing components in your React application, a well-defined structure is crucial for maintainability and scalability. By following a consistent and intuitive folder structure, you can easily locate and manage your components, promoting code reuse and modularity. Let’s explore some best practices for organizing your components effectively.

UI Components

When adding UI components, you should be able to group them into three root domains:

core – primitives, low level components

shared – components that are shared across the whole app

features – root folder for components based on a specific feature (could be scoped by page or island)

Folder naming rules:

kebab-case folder name indicates domain name

PascalCase folders and filenames should be used for naming components

src
 ├── components
 │   ├── core
 │   │   ├── Section
 │   │   │   └── Section.tsx
 │   │   └── Card
 │   │       └── Card.tsx
 │   ├── features
 │   │   ├── home
 │   │   │   ├── HomeHeaderSection
 │   │   │   │   └── HomeHeaderSection.tsx
 │   │   │   └── HomeTodoListSection
 │   │   │       └── HomeTodoListSection.tsx
 │   │   └── todo
 │   │       ├── TodoHeaderSection
 │   │       │   └── TodoHeaderSection.tsx
 │   │       └── TodoCreateFormSection
 │   │           └── TodoCreateFormSection.tsx
 │   └── shared
 │       ├── fields
 │       │   └── TextField
 │       │       └── TextField.tsx
 │       ├── todo
 │       │   ├── TodoCard
 │       │   │   └── TodoCard.tsx
 │       │   ├── TodoList
 │       │   │   └── TodoList.tsx
 │       │   └── TodoCreateForm
 │       │       └── TodoCreateForm.tsx
 │       └── utilities
 │             ├── BugsnagErrorBoundary
 │             │   └── BugsnagErrorBoundary.tsx
 │             └── Meta
 │                 └── Meta.tsx
 └── pages
     ├── index.tsx
     └── todo
         └── [id]
             └── index.tsx

The Core domain

We can refer to these components as atoms, the smallest building blocks. They are highly reusable and composable. If you need some inspiration on how to split components into small segments, you can check the Open UI standard proposal. Components could be designed as Compound Components or “Black-Box” Components with good inversion of control interface, like ReactSelect.

Here are some examples of core components:

Components	Parts	Description
Card	`Card`, `CardImage`, `CardImageOverlay`, `CardTitle`, `CardDescription`, …	From these parts, you’ll be able to compose multiple more specific `molecules` like `ProductCard` or `UserCard`.
Section	`Section`, `SectionHeader`, `SectionBody`, ..	These might have multiple background schemes like `dimmed`, `inverted`, `light`.
Search	`Search`, `SearchInput`, `SearchEmpty`, `SearchResults`, …	`Search` uses context to provide shared state to other parts. `SearchInput` renders input and it could be placed anywhere in the DOM structure (for example, in the page `Header`). `SearchEmpty` and `SearchResults` handle switching between states and showing the result.
ReactSelect	`ReactSelect`, `./components/ClearIndicator`, `./components/Control`, …	The list of custom components can be found here.

Folder structure:

src
└── components
    └── core
        ├── Card
        │   └── Card.tsx
        ├── Section
        │   └── Section.tsx
        ├── Search
        │   └── Search.tsx
        └── ReactSelect
            └── ReactSelect.tsx

The Shared domain

These components can be considered molecules. They are more specific, and built out of atoms, i.e. core components. They can be shared between feature components, and encapsulate some specific logic of a feature.

We can split them into three domains:

UI – higher order user interface components

Entity – UI representation of data models

Utility – headless utility components

Shared UI domain

Component name is always composed out of two parts, Context + Domain. For example, InputField where Input is context and Field is domain.

Domains	Components	Description
`fields`	`Card`, `CardImage`, `CardImageOverlay`, `CardTitle`, `CardDescription`, …	Specific form fields prepared to be used with the React Hook Form library. Built out of multiple parts, for example `InputGroup`, `InputLeftElement`, Input from Chakra UI.
`overlays`	`UnsupportedBrowserOverlay`, `BugsnagErrorOverlay`	Components that cover the whole page and prevent users from interacting with the page to some degree.
`layouts`	`MainLayout`, `AdminLayout`	Components that are shared across pages and render the application shell (navigation and footer).
`messages`	`NoResultsMessage`, `EmptyListMessage`, `LoadingMessage`, `ErrorMessage`	Reusable message components that could be shared across pages for handling empty list results, loading states or ErrorBoundaries fallback.
`navigations`	`MainNavigation`, `AdminNavigation`	Different navigations used in layouts to support different app shell styles. They can handle user logged-in/logged-out states and mobile/desktop layouts.
`footers`	`MainFooter`, `AdminFooter`	Different footers used in layouts to support different app shell styles. Serves the same purpose as `navigations`.
`panels`	`ArticlesPanel`, `EventPanel`, `EventSidebarPanel`, `GroupPanel`	Specific panels that hold filtering dropdowns for narrowing down list results. Usually consists of a core `Panel` compound component for sharing styles and sorting dropdowns.
`markdowns`	`ArticleMarkdown`, `AnnouncementMarkdown`	Components that handle parsing of the markdown and styling of the generated HTML.
`icons`	`PlusIcon`, `TrashIcon`	SVG icons used throughout the application. The icons should be named by what they are, not where they are used, e.g. `TrashIcon` instead of `DeleteIcon` or `ExclamationCircleIcon` instead of `ErrorIcon`.

Folder structure:

src
 └── components
     └── shared
         └── fields
             └── TextField
                 └── TextField.tsx

Shared Entity domain

We can also refer to these components as molecules, but they are tied to a certain entity, for example an API data model, Algolia resource, or Google Map entity.

Component names are always composed out of two parts, Entity + Context. For example, TodoList where Todo is an entity and List is the context.

Domains	Components	Description
`todo`	`TodoList`, `TodoCreateForm`, `TodoCard`, …
`user`	`UserList`, `UserCreateForm`, `UserCard`, …	Primarily, they should accept an entity prop like this where `user` is a resource from the API, or on rare occasion they could accept primitive props like `resourceId` and perform resource fetching via `SWR`.
`ticket`	`TicketList`, `TicketCreateForm`, `TicketCard`, …

Folder structure:

src
 └── components
     └── shared
         └── todo
             └── TodoCard
                 └── TodoCard.tsx

Shared Utility domain

Utility components are usually headless components, which means that they don’t have any impact on the UI itself, but are still reusable declarative React components.

Domains	Components	Description
`utilities`	`Meta`, `BugsnagErrorBoundary`	`Meta` inserts `meta` tags into the document `head`. `BugsnagErrorBoundary` catches the error, triggers the Bugsnag report and renders fallback components.

For example, let’s see how the Meta component is used for injecting meta tags inside the document .

import React, { FC } from 'react';
import Head from 'next/head';

export const Meta: FC = () => {
  return (
    <Head>
      <link rel='icon' type='image/png' sizes='32x32' href='/favicon-32x32.png' />
      <link rel='icon' type='image/png' sizes='16x16' href='/favicon-16x16.png' />
      <link rel='shortcut icon' href='/favicon.ico' />
      <title>Infinum</title>
    </Head>
  );
};

Folder structure:

src
 └── components
     ├── shared
     │   ├── utilities
     │   │   └── Meta
     │   │       └── Meta.tsx
     …

The components folder

When adding a components folder, you are basically extracting smaller chunks of your main React component that are only going to be used in that component and nowhere else.

Note: There should only be one level of component nesting inside the components folder. In fact, we are considering renaming this folder from components to elements to avoid confusion with the project root components folder, but this is still to be defined.

In this example, the MainTable component has a unique header component that should be placed inside the /components folder because it contains some styles, translations and an icon.

export const TableHeader: FC<FlexProps> = (props) => {
  const { t } = useTranslation();
  return (
    <Flex align='center' p={20} {...props}>
      <Heading size='md' colorScheme='secondary' as='h3'>
        {t('table.title')}
      </Heading>
      <Button leftIcon={<ArrowForwardIcon />} colorScheme='teal' variant='solid'>
        {t('table.viewAll')}
      </Button>
    </Flex>
  );
};

The folder structure should look something like this:

src
 └── components
     └── features
         └── some-feature
             └── MainTable
                 ├── components
                 │   └── TableHeader.tsx
                 └── MainTable.tsx

Elements

If you have a lot of style declarations inside your component file, enough to make the file difficult to read, you should create a separate file ComponentName.elements.ts and store your custom components there.

Example:

.
 └── WelcomeCard
     ├── WelcomeCard.tsx
     └── WelcomeCard.elements.ts

In the following example, WelcomeCardLayoutOverlay is a Pure Functional Component because the Chakra UI factory doesn’t allow the custom isOpen prop.

import { chakra, HTMLChakraProps, ThemingProps, useStyleConfig } from '@chakra-ui/react';

export const WelcomeCardLayout = chakra(Grid, {
  baseStyle: {
    gridTemplateRows: '1fr min-content min-content',
    gridTemplateColumns: '1fr min-content',
    rowGap: '16px',
  },
});

export const WelcomeCardLayoutContent = chakra(GridItem, {
  baseStyle: {
    position: 'relative',
    gridRowStart: '1',
    gridRowEnd: 'auto',
    gridColumnStart: '1',
    gridColumnEnd: 'auto',
  },
});

export interface WelcomeCardLayoutOverlayProps extends TMLChakraProps<'div'> {
  isOpen?: boolean;
}

export const WelcomeCardLayoutOverlay = forwardRef<WelcomeCardOverlayProps, 'div'>(
  ({ isOpen, ...rest }, ref) => {
    const height = isOpen ? { base: '300px', md: '500px' } : null;

    return (
      <GridItem ref={ref} h={height} position='relative' column='1 / 3' row='1 / 2' {...rest} />
    );
  }
);

Moving component parts to .elements.tsx should be the last step in the development process and it should only be used for organizational purposes, i.e. when the main component becomes cluttered and unreadable.

Here are some rules that you should follow when creating elements:

.elements.tsx should only be used for organizational purposes
Custom components are tightly coupled with the root component and they should not be used in the outside scope
Mixture of chakra factory and Function Components is allowed
Using hooks inside elements is not recommended
Wrapping in forwardRef is recommended but not mandatory (you need this in case you want to access real DOM element in the root component)

Note: For more information check the Chakra UI – Style Props section in our Handbook.

Different component layouts for different screen sizes

In most cases we’re striving to create responsive components that consist of one DOM structure that is going to be rendered on all screen sizes by utilizing CSS-only solutions. Work closely with your designer to achieve this.

However, there are cases when we need to create different DOM structures for different screen sizes.

Collocating different layouts in one component

With the help of Chakra UI Display helper props:

export const UserCard = (props) => {
  return (
    <Box {...props}>
      <Box hideFrom='md'>
        // Mobile layout
      </Box>
      <Box hideBelow='md'>
        // Desktop layout
      </Box>
    </Box>
  )
}

Different component layouts for different screen sizes in separate `layout` components

In this case, inside a specific component, we could add a subfolder layouts (not to be confused with the actual layout described below) to define how our component would look like on a specific media query.

We advise using this approach only for those layouts that would add too much complexity when using Chakra UI Display helper props. We realize that this approach usually results in a lot of code duplication, so it’s best to use it only when necessary.

.
 └── admin
     └── UserCard
         ├── layouts
         │   ├── UserCard.mobile.tsx
         │   └── UserCard.desktop.tsx
         └── UserCard.tsx

For this case, inside UserCard.tsx we would have something like this:

With the help of Chakra UI Display helper props:

export const UserCardMobile = () => (
  <Box hideFrom='md'>
    // Mobile layout
  </Box>
)

export const UserCardDesktop = () => (
  <Box hideBelow='md'>
    // Desktop layout
  </Box>
)

export const UserCard = () => {
  return (
    <Fragment>
      <UserCardMobile />
      <UserCardDesktop />
    </Fragment>
  )
}

With help of Chakra UI Show/Hide:

import { Show, Hide } from '@chakra-ui/react';

export const UserCard = () => {
  return (
    <Fragment>
      <Hide above="md">
        <UserCardMobile />
      </Hide>
      <Show above="md">
        <UserCardDesktop />
      </Show>
    </Fragment>
  )
}

Use of Show/Hide helpers is advisable to be used only for client side rendering. For server side rendering use Display helper props.

Extracting utility functions and hooks

Sometimes, you will have complex functions or effects inside your React component that will affect the readability of your component. In that case, you should extract them into separate files: *.utils.ts and *.hooks.ts.

The main goal of these files is to store functions and hooks that are specific for that component, so we could keep our root hooks and utils folders clean and for global usage purposes only. If you would like to know more, we’ve written about React hooks in class components before.

Folder structure example:

.
 ├── …
 └── AlbumsCarousel
     ├── AlbumsCarousel.tsx
     └── AlbumsCarousel.utils.ts
     └── AlbumsCarousel.hooks.ts

Cluttered component example:

export const AlbumsCarousel = (props) => {
  const [isPlaying, setIsPlaying] = useState(true);
  const [highlighted, setHighlighted] = useState(null);
  const [zoom, setZoom] = useState(1);

  const modals = useModals();
  const carouselRef = useRef();

  const showLoginModal = () => {
    modals.open(Modals.Login);
  };

  const highlightAlbum = (id: number) => {
    setIsPlaying(false);
    setHighlighted(id);
    carouselRef.current.collapseItems();
  };

  const formatReleaseDate = (startDate: string, endDate: string) => {
    const start = new Date(startDate);
    const end = new Date(endDate);
    const timezonedStart = new Date(start.valueOf() + start.getTimezoneOffset() * 60 * 1000);
    const timezonedEnd = new Date(end.valueOf() + end.getTimezoneOffset() * 60 * 1000);

    if (isSameDay(timezonedStart, timezonedEnd)) {
      return `${format(timezonedStart, 'd MMMM yyyy')}`;
    }

    if (!isSameYear(timezonedStart, timezonedEnd)) {
      return `${format(timezonedStart, 'd MMMM yyyy')} ${String.fromCharCode(8212)} ${format(
        timezonedEnd,
        'd MMMM yyyy',
      )}`;
    }

    if (!isSameMonth(timezonedStart, timezonedEnd)) {
      return `${format(timezonedStart, 'd MMMM')} ${String.fromCharCode(8212)} ${format(
        timezonedEnd,
        'd MMMM yyyy',
      )}`;
    }

    return `${format(timezonedStart, 'd')} ${String.fromCharCode(8212)} ${format(
      timezonedEnd,
      'd MMMM yyyy',
    )}`;
  }

  return (
    //...
    <div>{formatReleaseDate(props.startDate, props.endDate)</div>
    //...
  )
}

Clean component:

import { formatReleaseDate } from './AlbumsCarousel.utils.ts';

export const AlbumsCarousel = (props) => {
  const [isPlaying, setIsPlaying] = useState(true);
  const [highlighted, setHighlighted] = useState(null);
  const [zoom, setZoom] = useState(1);

  const modals = useModals();
  const carouselRef = useRef();

  const showLoginModal = () => {
    modals.open(Modals.Login);
  };

  const highlightAlbum = (id: number) => {
    setIsPlaying(false);
    setHighlighted(id);
    carouselRef.current.collapseItems();
  };

  return (
    //...
    <div>{formatReleaseDate(props.startDate, props.endDate)</div>
    //...
  )
}

Note: You can find out more about hook encapsulation in our handbook.

Layouts

With Layouts, we generally define the overall page structure that will be presented to the user based on a specific auth state or a specific page.

For example, your app can have an Admin dashboard on the /admin route which has a fixed header and sidebars on both right and left, and scrollable content in the middle (you’re most likely familiar with this kind of layout).

You define your different layouts inside the layouts folder:

.
└── components
    └── layouts
        ├── AdminLayout
        │   └── AdminLayout.tsx
        ├── MainLayout
        │   └── MainLayout.tsx
        └── BlogLayout
            └── BlogLayout.tsx

Then, when creating your routes (pages), you wrap your page in the layout that represents the current page:

// pages/index.tsx
export default function Home() {
  return <MainLayout>...</MainLayout>;
}

// pages/admin.tsx
export default function Admin() {
  return <AdminLayout>...</AdminLayout>;
}

Note: This section is preparation for the new Next.js App folder structure.

Setting up the global store

At Infinum we use our own solution for global data management and remote data fetching, called Datx. You can read more about working with JSON API, hassle-free in one of our previous blog posts.

Our Datx store and models will be placed in the root of the src folder as follows:

src
├── models
│   ├── User.ts
│   └── Session.ts
└── datx
    └── create-client.ts

Note: we have recently released the @datx/swr (doc) package which is a wrapper around SWR library. This is recommended for fetching data from the API using the JSON:API specification.

Setting up theming and styles

When creating styles for your core components, you will create the components folder inside the styles folder. The styles folder will contain all core stylings and the theme setup.

src
└── styles
    └── theme
        ├── index.ts # main theme endpoint
        ├── styles.ts # global styles
        ├── foundations # colors, typography, sizes...
        │   ├── font-sizes.ts
        │   └── colors.ts
        └── components # components styles
            └── button.ts

Tests

Here are a couple of quick rules to follow when organizing test files:

Components, utils, fetchers, etc. should have a test file in the same folder where they are placed
When testing pages, create the __tests__/pages folder, because of how Next.js treats the pages folder
All mocks should be placed in the __mocks__ folder

For other in-depth guides for testing, take a look at the testing guide.

Your folder structure should look something like this:

src
.
├── __mocks__
│   └── react-i18next.tsx
├── __tests__
│   ├── pages
│   │   └── user.test.ts
│   └── test-utils.tsx
├── pages
│   └── user.ts
└── components
    └── shared
        └── core
            └── Button
                ├── Button.test.tsx
                └── Button.tsx

A well-defined React project structure goes a long way

Organizing your React project folder structure is crucial for maintainability and scalability. At Infinum, we have established a well-defined structure that categorizes components into different domains: core, shared, and features.

By embracing Chakra UI and leveraging concepts such as compound components and the inversion of control interfaces, we foster the creation of highly composable and customizable core components.

Adopting a consistent and well-defined React native project structure for components enables development teams to easily locate and understand the purpose of each component. This approach promotes code reuse, modularity, and improves collaboration among team members. Ultimately, an organized folder structure paves the way for a more maintainable and scalable codebase.

The complete folder structure presented in this article can be found in our handbook.

The post Get Your Components in Order with React Project Structure appeared first on Infinum.

Panda CSS – CSS-in-JS without Runtime Overhead

Ivica Batinić — Thu, 13 Apr 2023 15:52:17 +0000

CSS-in-JS concept has a bad reputation because of its bad runtime performance. This is about to change. With Panda CSS, you can have the best of both worlds, performance and nice syntax – and we have the code examples and runnable projects to prove it.

Update note, 20 June 2023: This article has been updated based on the official documentation. For the latest information, please visit https://panda-css.com/docs.

As front-end developers, we’re always looking for tools and libraries that streamline our workflow and improve the performance of our web applications. One such promising solution that has caught my attention is Panda CSS. With Panda CSS, we can simplify front-end styling and completely eliminate the runtime overhead of CSS-in-JS libraries, making it a compelling choice for modern web development.

This blog post will dive into the basics of setting up Panda CSS and explore the key features that make it a standout tool for front-end development. From installation to usage, we will cover the steps to get started with Panda CSS and discover how it can help us achieve efficient and optimized styling in our web applications.

So let’s get started with this exciting new addition to the front-end development ecosystem!

Chakra UI – a development workflow game-changer

As a Lead React Engineer with a strong passion for React and a special love for Chakra UI, which I have been using for the past two years, I’m excited to share my thoughts on the future of this powerful component library. Chakra UI has been a game-changer in my development workflow, solving challenges like delivery speed, providing a basic component library, and managing design tokens for consistent UIs.

Looking ahead, the Chakra UI team is actively working on enhancements, including integrating Panda CSS to eliminate the runtime overhead of CSS-in-JS, resulting in even faster and more optimized UIs.

In addition to my insights, the author of Chakra UI, Adebayo Segun, has also shared his thoughts on the future of Chakra UI in a recent blog post, providing further insights and perspectives on what’s to come for this popular component library.

Panda CSS – frontend styling, simplified

Panda CSS is a utility CSS library that provides a set of utility classes, patterns, and recipes for building modern and responsive user interfaces in Web applications.

In addition, it offers a declarative approach to styling components using JavaScript objects, making it more readable and maintainable than pure string-based approaches. Similar to Tailwind CSS, Panda CSS enables developers to customize styles easily, and more details about its features will be revealed in step 3 below.

Get started with Panda CSS in three steps

Install Next.js

If you haven’t already, install create-next-app globally on your local machine using pnpm, npm, or yarn.

You can use the following command to create a new Next.js project with TypeScript:

npx create-next-app@latest --use-npm

Here are my answers to the prompts:

What is your project named? test-app
Would you like to use TypeScript with this project? Yes
Would you like to use ESLint with this project? Yes
Would you like to use Tailwind CSS with this project? No
Would you like to use src/ directory with this project? Yes
Use App Router (recommended)? Yes
Would you like to customize the default import alias? @/*

This will create a new Next.js project with a TypeScript template, which we will use as the base for our Panda CSS setup.

Enter the newly created directory:

cd test-app

Setup Panda CSS

Install @pandacss/dev:

First off, install Panda CSS as a dependency in your Next.js project and initialize it.

You can run the following commands:

npm install -D @pandacss/dev
npx panda init --postcss

The panda init --postcss command will automatically create a postcss.config.js file at the root of your project with the following code:

module.exports = {
   plugins: {
     '@pandacss/dev/postcss': {},
   },
 }

Update package.json scripts:

Update the scripts section in your project’s package.json file to include the necessary Panda CSS scripts. Replace the “dev” script with the following:

"scripts": {
   "prepare": "panda codegen",
   "dev": "next dev",
   "build": "next build",
   "start": "next start",
   "lint": "next lint"
}

This is the prepare script that will run codegen after dependency installation. You can read more about codegen in the CLI section of the official documentation.

Set up the configuration using the PostCSS plugin:

Set up custom PostCSS configuration

Follow the Next.js PostCSS guide to set up a custom PostCSS configuration by referring to this link.

Install additional dependencies:

npm install postcss-flexbugs-fixes postcss-preset-env

Uninstall “concurrently” if it was previously installed:

npm uninstall concurrently

Update your PostCSS configuration

Update your PostCSS configuration to include the Panda CSS PostCSS plugin:

{
  "plugins": [
    "postcss-flexbugs-fixes",
    [
      "postcss-preset-env",
      {
        "autoprefixer": {
          "flexbox": "no-2009"
        },
        "stage": 3,
        "features": {
          "custom-properties": false
        }
      }
    ],
    ["@pandacss/dev/postcss", {}]
  ]
}

Configure the content:

Open the panda.config.ts file in the root of your Next.js project directory. This file will serve as the configuration file for Panda CSS.

You can start with a basic configuration, such as:

import { defineConfig } from "@pandacss/dev";

export default defineConfig({
  // Whether to include css reset styles in the generated css.
  preflight: true,

  // Where to look for your css declarations
  include: ["./src/components/**/*.{ts,tsx,js,jsx}", "./src/app/**/*.{ts,tsx,js,jsx}"],

  // Used to create reusable config presets for your project or team.
  presets: ["@pandacss/dev/presets"],

  // Files to exclude
   exclude: [],

  // The framework to use for generating supercharged elements.
  jsxFramework: "react",

  // The output directory.
  outdir: "styled-system",
});

Configure the entry CSS with layers:

In your Next.js project, navigate to the src/app folder and open the global.css file. Replace all the content with the following code:

@layer reset, base, tokens, recipes, utilities;

Update Next.js layout (layout.tsx) and index page (page.tsx):

In your Next.js project, navigate to the layout.tsx file located at src/app/layout.tsx. Make sure that ./globals.css is imported at the beginning of that file.

The final snippet for layout.tsx would look like this:

import './globals.css'

export const metadata = {
  title: 'Hello ?!',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    l lang="en">
      <body>{children}</body>
    html>
  )
}

Also, delete all the default CSS files, for example src/app/page.module.css.

Next, you can update the contents of page.tsx with the following snippet that uses Panda CSS:

import { panda } from '../../styled-system/jsx';
export default function Home() {
  return (
    v fontSize="24px">hello ?.div>
  )
}

Start the development server:

In your Next.js project, run the command npm run dev in your terminal to start the development server. This will launch your Next.js application locally at http://localhost:3000/ in your web browser.

After running the dev server, you should be able to see the panda folder with all the generated components in the root folder of your project. The components will be generated based on the styles defined in your Panda CSS configuration file (panda.config.ts) and the usage of the panda object in your components.

With these setup steps, you will be ready to use Panda CSS in your Next.js project and leverage its powerful features for creating responsive and customizable CSS styles.

Customize styling

Panda CSS provides a set of default styles for its components, but you can easily customize the styling to match your project’s design.

Theme

One of the powerful features of Panda CSS is the ability to customize the theme according to your project’s specific needs. You can easily define your own color palettes, typography, spacing, and more to create a unique visual style for your application.

To customize the theme, you can define your own theme configuration in a panda.config.ts file. For example, you can add a custom color gradient called “infinum” to your theme:

import { defineConfig } from "@pandacss/dev";

export default defineConfig({
  //...

  theme: {
    extend: {
      tokens: {
        colors: {
          infinum: {
            50: { value: '#FBE9EA'},
            100: { value: '#F7D3D5'},
            200: { value: '#EFA8AB'},
            300: { value: '#E77D81'},
            400: { value: '#E05257'},
            500: { value: '#D8262C'},
            600: { value: '#BD2127'},
            700: { value: '#A21C21'},
            800: { value: '#87171C'},
            900: { value: '#6C1216'},
          },
        },
      },
    },
  },
});

After defining the custom color gradient in your theme configuration, you can easily apply it to your component:

<panda.div 
  color="infinum.400"
>
  hello ?
panda.div>

Note: This will use ‘#E05257’ color from our custom theme.

Patterns

Panda CSS patterns are common layout building blocks that provide pre-designed styles and configurations for elements such as box container, flex containers, grid containers, grid items, and more. These patterns are included by default in Panda CSS and can be easily used in your Next.js projects.

You can also extend or customize these patterns in your project by adding additional configurations in the panda.config.ts file.

import { defineConfig } from "@pandacss/dev";

export default defineConfig({
  //...

  patterns: {
    extend: {
      container: {
        transform(props) {
          // TODO descructuring props.centerContent is not working @panda
          delete props.centerContent;

          return Object.assign(
            {
              position: "relative",
              width: "100%",
              maxWidth: "7xl",
              mx: "auto",
              paddingX: { base: "4", md: "6" },
            },
            props
          );
        },
      },
    },
  },
});

And this is how you can use container pattern with the simple div:

import { panda } from '../../styled-system/jsx';
import { container } from '../../panda/patterns';

export default function Home() {
  return (
    v className={container({})}>
      v fontSize="24px">hello ?da.div>
    </div>
  )
}

Or, by using JSX component:

import { Container, panda } from '../../styled-system/jsx';

export default function Home() {
  return (
    iner>
      v fontSize="24px">hello ?da.div>
    iner>
  )
}

In the browser, it looks like this:

This way, you can easily customize and extend the default patterns provided by Panda CSS to suit your specific layout requirements in your Next.js project.

Recipes

Panda CSS allows you to create pre-defined styles for common UI components, referred to as “recipes.” These recipes include styles for core components such as accordions, buttons, links, selects, and more. Recipes are designed to be highly customizable and can be easily extended or overridden to match your specific design requirements.

You can configure and extend the default set of recipes or add additional recipes to your project’s Panda CSS configuration file, panda.config.ts.

For example, you can define a recipe for a custom Link component:

First, we need to create a recipe:

import { defineConfig } from "@pandacss/dev";

export default defineConfig({
  //...
  theme: {
    extend: {
      //...
      recipes: {
        link: {
          name: "link",
          description: "A link styles",
          base: {
            // some base styles
          },
          variants: {
            variant: {
              primary: {
                color: "infinum.500",
                textDecoration: "underline",
                _hover: {
                  color: "infinum.600",
                },
                _active: {
                  color: "infinum.700",
                },
              },
              unstyled: {
                color: "inherit",
                textDecoration: "none",
              },
            },
          },
          defaultVariants: {
            variant: "primary",
          },
        },
      },
    },
  },
});

Then, we need to create a custom Link component and apply the recipe. We will also use Next.js Link component as the base:

import { cx } from '../../../styled-system/css';
import { panda, type HTMLPandaProps } from '../../../styled-system/jsx';
import { link, type LinkVariants, } from '../../../panda/recipes';
import NextLink, { type LinkProps as NextLinkProps } from 'next/link'

export type LinkProps = LinkVariants & { href: NextLinkProps['href'] } & HTMLPandaProps<'a'>;

export const Link = (props: LinkProps) => {
  const { href, variant, content, className, ...rest } = props;

  return (
    k legacyBehavior href={href} passHref>
      a className={cx(className, link({ variant }))} {...rest} />
    Link>
  );
}

Then we can use it like this:

import { Container, panda } from '../../panda/jsx';
import { Link } from '@/components/core/Link';

export default function Home() {
  return (
    iner>
      k href="/panda">Go to Panda page</Link>
    iner>
  )
}

In the browser, it looks like this:

If you prefer not to write your components from scratch, you can leverage the pre-defined components available in the Ark-UI library at ark-ui.com, saving time and effort in building your user interfaces.

Advanced Usage of Panda CSS: Implementing Animated Card Hover Effects

The complex example section demonstrates how to implement a card with animation on hover using Panda CSS, showcasing the versatility and flexibility of the library for creating complex and interactive user interfaces with ease.

import { Link } from "@/components/core/Link";
import { Container, panda } from "../../styled-system/jsx";

export default function Home() {
    return (
        <Container display="flex" justifyContent="center" py="10">
            <Link
                href="/panda"
                variant="unstyled"
                className="group"
                display="flex"
                flexDirection="column"
                alignItems="center"
                maxW="300px"
                fontFamily="sans"
                borderWidth="1px"
                borderColor="gray.200"
                borderRadius="3xl"
                shadow="md"
                transition="all 0.2s"
                _hover={{
                    transform: 'translateY(-2px)',
                    shadow: 'lg',
                }}
            >
                <panda.div
                    display="block"
                    fontSize="9xl"
                    _groupHover={{
                        animation: 'spin 1s infinite',
                    }}
                >
                    ?
                panda.div>
                <panda.h2 fontSize="2xl" mb="2">
                    Panda CSS
                panda.h2>
                <panda.div color="gray.900" p="4">
                    Because why settle for just regular bear CSS when you can have a cute,
                    powerful, and flexible framework like Panda CSS to make your web
                    development roar with excitement!
                panda.div>
            Link>
        Container>
    );
}

In the video demonstration below, you can see the Card component rendered in the browser, showcasing the implementation of the code snippet above.

Live link: https://js-panda-css.vercel.app/

Start experimenting with Panda CSS

That’s it! You’re ready to start using Panda CSS in your Next.js project. With its simplified approach to front-end styling, Panda CSS can help you streamline your development workflow and create efficient and optimized web applications. Happy coding!

The post Panda CSS – CSS-in-JS without Runtime Overhead appeared first on Infinum.

Author at Infinum

Get Your Components in Order with React Project Structure

Organizing components in React project structure

UI Components

The Core domain

The Shared domain

Shared UI domain

Shared Entity domain

Shared Utility domain

The components folder

Elements

Different component layouts for different screen sizes

Collocating different layouts in one component

Different component layouts for different screen sizes in separate layout components

Extracting utility functions and hooks

Layouts

Setting up the global store

Setting up theming and styles

Tests

A well-defined React project structure goes a long way

Panda CSS – CSS-in-JS without Runtime Overhead

Chakra UI – a development workflow game-changer

Panda CSS – frontend styling, simplified

Get started with Panda CSS in three steps

Install Next.js

Setup Panda CSS

Install @pandacss/dev:

Update package.json scripts:

Set up the configuration using the PostCSS plugin:

Set up custom PostCSS configuration

Install additional dependencies:

Uninstall “concurrently” if it was previously installed:

Update your PostCSS configuration

Configure the content:

Configure the entry CSS with layers:

Update Next.js layout (layout.tsx) and index page (page.tsx):

Start the development server:

Customize styling

Theme

Patterns

Recipes

Advanced Usage of Panda CSS: Implementing Animated Card Hover Effects

Start experimenting with Panda CSS

Different component layouts for different screen sizes in separate `layout` components