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)
                -shared/
                    -ComponentName.tsx
                -componentName/
                    -ComponentName.tsx
            - utils/ (Utility functions directory)
                -calculate-tools.ts
                -custom-helper.tsx
            - hooks/
                -useCustomHook.tsx
            - types/
                -type.ts
            - graphql/ (GraphQL-related code directory)
                -user-query.ts
            - ... (Additional directories as needed)

        - pages/ (Next.js pages directory)
            -about-us-page.tsx
        - 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.

Conclusion

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!