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.

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.

Sass (SCSS)

All related files can be found within the styles 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.


⚠️ **GitHub.com Fallback** ⚠️