Structuring a Next.js Project in Sitecore XM Cloud

A Guide to Structuring a Next.js XM Cloud Project

Discover how to unleash the full potential of Sitecore XM Cloud by implementing a streamlined and adaptable folder hierarchy for your Next.js project. Based on industry best practices, our guide will show you how to incorporate Tailwind CSS, TypeScript, Storybook, and GraphQL into your development workflow, resulting in a more efficient and effective project management process.

Next.js Folder Structure in XM Cloud

Having a well-structured folder hierarchy is essential to keep your project organized and scalable. Here's a high-level overview of the recommended folder structure:

- companyx-nextjs/
   - src/ (Source code directory)
        - app/ 
            - components/ (Components directory)
            - utils/ (Utility functions directory)
            - hooks/
            - types/
            - graphql/ (GraphQL-related code directory)
            - ... (Additional directories as needed)

        - pages/ (Next.js pages directory)
        - styles/ (Stylesheets directory contain any global styles or custom CSS )
        - stories/
        - assets/
        - ... (Additional application directories if necessary)
    - public/ (Public directory for static assets)
    - ...
    - next.config.js (Next.js configuration file)
    - tailwind.config.js (Tailwind CSS configuration file)
    - postcss.config.js (PostCSS configuration file)
    - tsconfig.json (TypeScript configuration file)
    - package.json (Project dependencies and scripts)
    - ...

Src Folder

It's essential to use a src/ directory as the core of your application to ensure proper project organization. This directory should have GraphQL queries, global styles, assets, and TypeScript types subfolders. The advantages of utilizing a src/ directory include a cleaner project root, more straightforward navigation, better code isolation, and compatibility with specific tools and configurations. Separating your source files in a directory is crucial to keep your project root folder tidy and avoid cluttering it with various files. This approach also makes your project more manageable and maintainable in the long run.

App Folder

The app folder provides a clear and structured foundation for the core application code, fostering better development practices, promoting code reusability, and facilitating a more maintainable and scalable Next.js project on Sitecore XM Cloud.

Components Folder

It's a good practice to have a shared folder and separate folders for each component in the components folder. Here's why:

  1. Shared Folder: Placing shared components in a dedicated shared folder promotes code reusability and ensures that standard components can be easily accessed and utilized across different application parts. These shared components typically consist of buttons, input fields, modals, or other UI elements used in multiple places throughout the application.
  2. Separate Folders for Each Component: Creating different folders for each component allows for better organization and isolation of the component's code. Each folder can contain the component's specific implementation, associated CSS files, and any additional files relevant to that component. This approach is known as "CSS Modules" and is recommended.
  3. utils folder: Storing utility functions in a separate utils folder can help improve code organization and maintainability. By grouping common functionalities together, you can enhance code reusability and make it easier to find and reference specific functions when needed.
  4. hooks folder: To make your code modular and maintainable, store custom React hooks in the hooks folder. This way, you can easily reference and reuse them throughout your project.
  5. types folder: Ensure you incorporate TypeScript definitions within your project’s “types” folder. This practice will boost type safety, deliver comprehensive code documentation, and foster better development practices.
  6. graphql folder:Within the graphql folder, GraphQL-related code, such as queries and mutations, is centralized, enabling clear separation of concerns and streamlining data interactions with the backend.

Pages Folder

Organize your pages in Next.js by grouping them logically within the pages folder to ensure a seamless user experience.

Here's how the requested pages can be organized within the pages/ folder of your Next.js project:

- pages/
  - index.tsx
  - about.tsx
  - products/
    - index.tsx
    - [productId].tsx

Styles Folder

The styles folder contains global styles or custom CSS files for the Next.js project, allowing consistent styling across components and pages.

Stories Folder

The stories folder is used with Storybook to store individual stories for components, enabling interactive component development and documentation.

Assets Folder

The assets folder holds static assets, such as images, fonts, and other files, that need to be publicly accessible from the browser.

Public Folder

The public folder is where you store static assets such as images, fonts, and other files that need to be directly accessible from the browser.


Developing a successful Next.js project integrated with Tailwind CSS, TypeScript, Storybook, and GraphQL for Sitecore XM Cloud relies on a well-structured folder layout. Embracing this organized approach enhances code organization, readability, and collaboration among team members, ensuring a seamless and productive development process.

By adhering to this recommended folder structure, you'll create web applications with Next.js that are efficient, maintainable, and scalable to meet future needs. So, let's dive in and get coding! Your projects are bound to thrive with this structured foundation in place. Happy coding, and best of luck on your Sitecore XM Cloud journey!

👋 Hey Sitecore Enthusiasts!

Sign up to our bi-weekly newsletter for a bite-sized curation of valuable insight from the Sitecore community.

What’s in it for you?

  • Stay up-to-date with the latest Sitecore news
  • New to Sitecore? Learn tips and tricks to help you navigate this powerful tool
  • Sitecore pro? Expand your skill set and discover troubleshooting tips
  • Browse open careers and opportunities
  • Get a chance to be featured in upcoming editions
  • Learn our secret handshake
  • And more!
Sitecore Snack a newsletter by Fishtank Consulting

Meet Sohrab Saboori

Senior Full-Stack Developer


Sohrab is a Senior Front-End Developer with extensive experience in React, Next.js, JavaScript, and TypeScript. Sohrab is committed to delivering outstanding digital solutions that not only meet but exceed clients' expectations. His expertise in building scalable and efficient web applications, responsive websites, and e-commerce platforms is unparalleled. Sohrab has a keen eye for detail and a passion for creating seamless user experiences. He is a problem-solver at heart and enjoys working with clients to find innovative solutions to their digital needs. When he's not coding, you can find him lifting weights at the gym, pounding the pavement on the run, exploring the great outdoors, or trying new restaurants and cuisines. Sohrab believes in a healthy and balanced lifestyle and finds that these activities help fuel his creativity and problem-solving skills.

Connect with Sohrab