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.
codebase/ β The root directory containing all project code, configuration, and system documentation
β
βββ .github/ β GitHub-specific configuration (e.g., issue templates, workflows, community files)
β
βββ backend/ β Full Laravel (API-only) project with routes, domain logic, migrations, tests, and a Backpack admin panel
β
βββ docs/ β Internal notes for system behavior, architecture, and implementation details
β
βββ frontend/ β Next.js application with pages, components, configs, and supporting utilities
β β
β βββ .next/ β Folder where Next.js puts files it builds to run the app
β β
β βββ cache/ β Temporary files used to speed up builds and development tools
β β
β βββ lang/ β JSON files with translations used for multi-language support across the app
β β
β βββ public/ β Static files that are served directly to the browser
β β βββ favicon/ β Icons used for browser tabs and bookmarks
β β βββ fonts/ β Licensed or external fonts (not served by Google Fonts)
β β βββ images/ β Pictures used across the site
β β βββ videos/ β Video files used across the site
β β βββ js/ β JavaScript libs and files that run outside the Next.js lifecycle
β β
β βββ src/ β Core source code of the application
β β β
β β βββ app/[lang]/ β Next.js routes, layouts, and middleware for handling pages by language
β β β βββ dictionaries.js/ β Load translations at runtime, based on the language in the route
β β β βββ layout.js β Root layout file that wraps the entire app's UI
β β β βββ loading.js/ β Fallback UI shown while a page is loading
β β β βββ page.js β Page component for the current route
β β β βββ ... β Additional app-related files
β β β
β β βββ assets/ β Style and design resources
β β β βββ bessex/ β bEssEx (Bootstrap fork)
β β β βββ css/ β External CSS libraries (including Tailwind entry point)
β β β βββ scss/ β Custom SCSS engine (variables, mixins, etc.)
β β β
β β βββ components/ β Reusable UI components
β β β βββ alerts/ β User-facing alerts and notifications
β β β β βββ events/ β Alerts for general events (not tied to user profile)
β β β β βββ registration/ β Alerts for profile updates and registration actions
β β β βββ blocks/ β Self-contained blocks of reusable UI
β β β βββ dialogs/ β Interactive prompts such as modals and forms
β β β βββ elements/ β Small, granular UI elements
β β β βββ footers/ β Footer components
β β β βββ navbars/ β Navigation-related components
β β β
β β βββ config/ β Project-wide constants
β β β βββ settings.js β Global app settings (e.g., theme, language options)
β β β
β β βββ hooks/ β Reusable functions that get information while the user is interacting with the site
β β β βββ useAuth.js β Handles authentication state
β β β βββ useSectionScroll.js β Scroll-based navigation logic
β β β βββ useTheme.js β Manages dark/light theme switching
β β β βββ ... β Any other custom hooks
β β β
β β βββ lib/ β Functions that run on the server to get info before rendering the page
β β β βββ server/ β Server-only versions of helpers for handling data before the page loads
β β β βββ server.js β Entry point that loads all server-side utilities in one place for easy access
β β β βββ auth.js β Authentication-related API calls
β β β βββ stripe.js β Payment processing integration
β β β βββ ... β Other third-party integrations
β β β
β β βββ providers/ β Components that make data available to multiple parts of the app through context
β β β βββ AuthProvider.js β Provides authentication context
β β β βββ Client.js β Wraps all hooks so their data can be used anywhere in the app
β β β βββ ContentProvider.js β Centralized content management
β β β βββ ThemeProvider.js β Manages global theme state
β β β βββ ... β Any other global providers
β β β
β β βββ utils/ β General helper functions and internal libraries (non-React utilities)
β β β βββ animations/ β Internal animation scripts bundled as part of the app for easy access
β β β βββ helpers/ β Generic utility functions shared across the app
β β β βββ manual/ β One-off scripts invoked manually, not part of the main bundle
β β β β βββ custom/ β Project-specific ad hoc scripts
β β β β βββ standalone/ β Scoped scripts loaded individually when needed, not included globally
β β β βββ 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
β β β
β β βββ middleware.js β Middleware logic that runs on every request to control redirects, authentication, or other request handling
β β
β βββ .env.local β Local environment variables like API keys, secrets, and base URLs
β βββ .gitignore β Files and folders Git should ignore
β βββ .prettierignore β Files and folders Prettier should skip formatting
β βββ .prettierrc β Rules for Prettier code formatting
β βββ next-env.d.ts β Auto-generated TypeScript definitions for Next.js
β βββ next.config.mjs β Next.js configuration file for routing, builds, images, and other framework settings
β βββ package.json β Lists project dependencies, scripts, and metadata
β βββ pnpm-lock.yaml β Locked package versions for consistent installs
β βββ postcss.config.mjs β Configuration for PostCSS (used by Tailwind)
β βββ rollup.config.mjs β Configuration for Rollup, a bundler that compiles all internal scripts into a single file
β βββ tsconfig.json β TypeScript configuration for module paths, type checking, and compiler behavior in the project
β
βββ .gitattributes β Settings for Git handling of files
βββ .gitignore β Lists files and folders Git should ignore
βββ LICENSE β License terms for using and sharing the project
βββ README.md β Project overview and usage instructions
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 thesrc
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.
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.
-
Next.js's App Router (available from version
13
) useslayout.js
as its top-level entry point, meaning that it's where the shared UI is placed. It contains:-
Fonts (applied to the
<html>
tag via CSS variables) -
HeadComponent.jsx
(spreads<head>
components into themetadata
object)- Favicon
- Scripts
- SEO
- Stylesheets
-
RootLayout
component (used to define the<html>
and<body>
tags and other globally shared UI) -
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" /> ```
-
-
page.js
(routes to the website's home page) -
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.
-
globals.css
/globals.scss
-
folders: app, components, hooks, styles
-
src/public
-
routes/aliases, can use JS and TSX together out-of-the-box
-
The only way a script file can be diretly included in Next.js is when placed on the public folder.
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
-
-
Default Exports: Pages in Next.js must use default exports, as Next.js automatically looks for these in the
pages
orapp
directory to render components. -
Named Exports: For components, named exports are used for naming consistency across the project, although either type is allowed.
-
-
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.
-
Use <Script /> in Next.js when you need to:
Load external JS libraries (e.g. Stripe, Google Maps, Analytics)
Inject inline scripts (e.g. for tracking or widgets)
Control load timing (beforeInteractive, afterInteractive, etc.)
β Client-side only β Not for app logic or server data processing
In JSX ternaries, that looks like this:
{condition1 ? (
// A
) : condition2 ? (
condition2_1 ? (
// B
) : condition2_2 ? (
// C
) : (
// fallback for condition2
)
) : condition3 ? (
// D
) : (
// final else
)}
That directly mirrors:
if (condition1) {
// A
} else if (condition2) {
if (condition2_1) {
// B
} else if (condition2_2) {
// C
} else {
// fallback for condition2
}
} else if (condition3) {
// D
} else {
// final else
}
-
Location:
/providers/GlobalProvider.jsx
- Purpose: Stores global state & shared API data
-
Includes:
useState
for data,createContext
, anduseContext
"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);
}
-
Location:
/app/[lang]/layout.js
- Wraps
<GlobalProvider>
aroundchildren
import { GlobalProvider } from "@/providers/GlobalProvider";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<GlobalProvider>{children}</GlobalProvider>
</body>
</html>
);
}
- 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>;
}
β
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. π
All related files can be found within the static
folder.
-
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. -
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 tostyle.scss
for compilation. -
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.
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.
-
partials files call the
_extends.scss
and_dynamics.scss
controllers. -
modules files call the
_dynamics.scss
controller. -
mixins files call the
_variables.scss
controller.
Generate here: RealFaviconGenerator
- Format: SVG (best) or PNG
- SVG β Scales perfectly (512x512px+ recommended)
- PNG β Use at least 512x512px (1024x1024px preferred)
- Proportions: Square (1:1 ratio)