File Linking Relationships - humanbit-dev-org/templates GitHub Wiki

In order to split code into logical blocks, the relationship structure between files is as follows.

Files are indented with four spaces, configured to the tab key.

Tree overview

 
/public                     β†’ Static assets (images, fonts, icons, etc.)
β”‚   β”œβ”€β”€ favicon.ico         β†’ App favicon
β”‚   β”œβ”€β”€ images/             β†’ Global images used across the app
β”‚   β”œβ”€β”€ fonts/              β†’ Custom fonts if not imported via Google Fonts
β”‚   └── uploads/            β†’ User-uploaded or dynamically generated assets
β”‚
/src                        β†’ The core source code of the application
β”‚
β”œβ”€β”€ /app/[lang]             β†’ Next.js routes, layouts, and middleware
β”‚   β”œβ”€β”€ layout.js           β†’ Root layout file (wraps the entire app)
β”‚   β”œβ”€β”€ page.js             β†’ Main app entry point
β”‚   β”œβ”€β”€ api/                β†’ API routes (server-side logic)
β”‚   β”œβ”€β”€ middleware.js       β†’ Middleware logic for handling requests
β”‚   └── ...                 β†’ Additional app-related files
β”‚
β”œβ”€β”€ /assets                 β†’ Global styles, Tailwind entry, and other CSS/SCSS
β”‚   β”œβ”€β”€ tailwind.css        β†’ Tailwind CSS initialization
β”‚   β”œβ”€β”€ global.scss         β†’ Global styles for the app
β”‚   β”œβ”€β”€ theme.scss          β†’ Light/dark mode styles
β”‚   β”œβ”€β”€ animations.scss     β†’ Global animations
β”‚   └── ...                 β†’ Any other static styles
β”‚
β”œβ”€β”€ /components             β†’ Reusable UI components (buttons, cards, modals, etc.)
β”‚   β”œβ”€β”€ blocks/             β†’ Self-contained blocks of reusable UI
β”‚   β”œβ”€β”€ dialogs/            β†’ Modals, popups, etc.
β”‚   β”œβ”€β”€ elements/           β†’ Granular reusable UI elements
β”‚   β”œβ”€β”€ footers/            β†’ Footer components
β”‚   β”œβ”€β”€ navbars/            β†’ Navigation-related components
β”‚
β”œβ”€β”€ /config                 β†’ Project-wide constants & environment settings
β”‚   β”œβ”€β”€ env.js              β†’ Environment variables and base URLs
β”‚   β”œβ”€β”€ api.js              β†’ API endpoints & configurations
β”‚   └── settings.js         β†’ Global app settings (e.g., theme, language options)
β”‚
β”œβ”€β”€ /hooks                  β†’ Custom React hooks for state & side effects
β”‚   β”œβ”€β”€ useAuth.js          β†’ Handles authentication state
β”‚   β”œβ”€β”€ useSectionScroll.js β†’ Scroll-based navigation logic
β”‚   β”œβ”€β”€ useTheme.js         β†’ Manages dark/light theme switching
β”‚   └── ...                 β†’ Any other custom hooks
β”‚
β”œβ”€β”€ /lib                    β†’ External services, API wrappers, and DB connections
β”‚   β”œβ”€β”€ db.js               β†’ Database connection setup (if applicable)
β”‚   β”œβ”€β”€ auth.js             β†’ Authentication-related API calls
β”‚   β”œβ”€β”€ stripe.js           β†’ Payment processing integration
β”‚   └── ...                 β†’ Other third-party integrations
β”‚
β”œβ”€β”€ /providers              β†’ Context API providers (global state management)
β”‚   β”œβ”€β”€ AuthProvider.js     β†’ Provides authentication context
β”‚   β”œβ”€β”€ ThemeProvider.js    β†’ Manages global theme state
β”‚   β”œβ”€β”€ ContentProvider.js  β†’ Centralized content management
β”‚   └── ...                 β†’ Any other global providers
β”‚
β”œβ”€β”€ /utils                  β†’ General helper functions (non-React utilities)
β”‚   β”œβ”€β”€ formatDate.js       β†’ Formats dates into readable formats
β”‚   β”œβ”€β”€ debounce.js         β†’ Prevents excessive function calls
β”‚   β”œβ”€β”€ fetchData.js        β†’ Simplifies API requests
β”‚   β”œβ”€β”€ domHelpers.js       β†’ Functions for DOM manipulation
β”‚   └── ...                 β†’ Other non-React utility functions
β”‚
└── package.json            β†’ Defines project dependencies and scripts

JavaScript & JSX

All related files are stored in the frontend folder:

  • Static assets, such as favicon, fonts, videos, and external scripts that need to be accessible to the public at a fixed URL are placed in the public folder.
  • Local files, including pages, components, and styles, are kept within the src folder (which is optional but common for organizing the source code).

Next.js's <Image /> component is highly effective at optimizing images, so placing images in the src folder allows them to take advantage of automatic optimization (like lazy loading, resizing, and serving in modern formats like WebP), which isn't possible if they're in the public folder.

External structure

For best practice, use .js for pages and .jsx for components (though both extensions are interchangeable).

The structure also supports .ts and .tsx versions out-of-the-box, as the router and aliases have been adapted for seamless use with both JavaScript and TypeScript.

  1. Next.js's App Router (available from version 13) uses layout.js as its top-level entry point, meaning that it's where the shared UI is placed. It contains:

    1. Fonts (applied to the <html> tag via CSS variables)

    2. HeadComponent.jsx (spreads <head> components into the metadata object)

      • Favicon
      • Scripts
      • SEO
      • Stylesheets

    3. RootLayout component (used to define the <html> and <body> tags and other globally shared UI)

    4. Outer wrapper classes:

      ```
<body className="bg_color_white fx_load" />
    <div className="container_humanbit_overflow scrollbar_spacing" id="page" />
        <div className="container_humanbit_structure container-fluid" />
```

    5. children (required) and params (optional) props

  2. page.js (routes to the website's home page)

  3. page.module.css/page.module.scss (Next.js's built-in CSS/Sass compiler)

    Next.js supports Sass Modules, which locally scope styles to components by compiling SCSS to CSS and dynamically injecting the styles into the page's <style> tag at runtime. This prevents style conflicts and optimizes CSS for both development (with hot reloading) and production (with minimized, tree-shaken styles). Global SCSS files are compiled into a separate CSS file in production.

    Tree-shaking ensures that only the CSS used by the current page or component is loaded.

  4. globals.css/globals.scss

  5. folders: app, components, hooks, styles

  6. src/public

  7. routes/aliases, can use JS and TSX together out-of-the-box

  8. The only way a script file can be diretly included in Next.js is when placed on the public folder.


Internal structure

Just as most things in JavaScript are handled as objects (even primitives behave like objects when accessed via methods), in JSX, every element or include can be considered a componentβ€”including pages.

An object is a collection of key-value pairs, where keys are strings (or symbols) and values can be any data type, including functions

  1. ES6 Module Exports #

    • Default Exports: Pages in Next.js must use default exports, as Next.js automatically looks for these in the pages or app directory to render components.

    • Named Exports: For components, named exports are used for naming consistency across the project, although either type is allowed.

  2. return statement

    • return ( ... ); is typically used when returning JSX elements (as in an HTML-like structure) within a component.
    • return { ... }; commonly used when returning an object from a function or method, possibly containing multiple key-value pairs.

Global Provider – Quick Manual

1️⃣ Create the Provider

  • Location: /providers/GlobalProvider.jsx
  • Purpose: Stores global state & shared API data
  • Includes: useState for data, createContext, and useContext 
"use client";
import { createContext, useContext, useState } from "react";

const GlobalContext = createContext();

export function GlobalProvider({ children }) {
  const [globalState, setGlobalState] = useState({});
  const [apiData, setApiData] = useState(null);

  return (
    <GlobalContext.Provider value={{ globalState, setGlobalState, apiData, setApiData }}>
      {children}
    </GlobalContext.Provider>
  );
}

export function useGlobalContext() {
  return useContext(GlobalContext);
}

2️⃣ Add It to Root Layout

  • Location: /app/[lang]/layout.js
  • Wraps <GlobalProvider> around children
import { GlobalProvider } from "@/providers/GlobalProvider";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <GlobalProvider>{children}</GlobalProvider>
      </body>
    </html>
  );
}

3️⃣ Use It in Any Component

  • Import & call useGlobalContext()
  • Read & update state
import { useGlobalContext } from "@/providers/GlobalProvider";

export default function MyComponent() {
  const { globalState, setGlobalState } = useGlobalContext();

  return <button onClick={() => setGlobalState({ clicked: true })}>Click</button>;
}

πŸ”Ή Summary

βœ… Store state & API data in GlobalProvider.jsx
βœ… Wrap the app in GlobalProvider (inside layout.js)
βœ… Access it anywhere with useGlobalContext()

Done. No prop drilling, global state available anywhere. πŸš€

Sass (SCSS)

All related files can be found within the static folder.

External structure

  1. A general upper-level entry point file (style.scss) calls (through the scoped loader @use rule) all mid-level controllers and acts as the sole compiling source.

  2. Four mid-level controllers (pages [_partials.scss], modules [_extends.scss], _mixins.scss and _variables.scss [the two latter combined into _dynamics.scss]) that @forward all the single files to style.scss for compilation.

  3. All the lower-level single files of each component type (pages [partials], extends [modules], mixins and _variables.scss) in which the style is actually written.

NOTEΒΉ: The scoped @use rule is encouraged by the Sass team rather than the global @import rule that will soon be deprecated due to its numerous conflicting issues.
NOTEΒ²: Since they're part of the main page structure, navigation bar, footer and general style modules are placed within the pages folder (partials) and called on the pages controller (_partials.scss) even though they're modular components, for intuitive display.


Internal structure

Different file types must call different controllers.
That is because since the @use rule is scoped, it's fundamentally impossible to globally relate all files to each other from a single high-level entry point as it would send them into a loop.
This was intended to avoid unexpected interactions, such as not being able to call mixins on a contained context.

  1. partials files call the _extends.scss and _dynamics.scss controllers.

  2. modules files call the _dynamics.scss controller.

  3. mixins files call the _variables.scss controller.


Favicon Guide

Generate here: RealFaviconGenerator

Recommended Source Image

  • Format: SVG (best) or PNG
  • SVG β†’ Scales perfectly (512x512px+ recommended)
  • PNG β†’ Use at least 512x512px (1024x1024px preferred)
  • Proportions: Square (1:1 ratio)
⚠️ **GitHub.com Fallback** ⚠️