Part III ➝ The anatomy of nextjs-sass-starter

[jimmylee]

What will I know after reading this?

Building a website with our stack will deepen your understanding of the technology we chose to build it with.

You will learn:

➝ An overview of the technology being used.
➝ An overview of the file organization. You will still need to read the NextJS documentation for a complete understanding.
➝ An overview of how to implement your own React Component.
➝ An overview of how to implement your first Page Router entry.

If you have any questions, feel free to ask!

Overview

This repository uses NextJS, so the project structure follows the common organization of NextJS projects.

NextJS pre-renders every page using JavaScript/TypeScript on both the client and server, unlike traditional client-side JavaScript in the browser. This approach can enhance performance and improve SEO. Additionally, it boosts productivity since you can stay within the JavaScript/TypeScript environment without switching languages.

Because this repository uses NextJS, it also uses:

➝ React, which is declarative and component-based. It allows us to logically reason about the interface and state that we are architecting. Our repository is an example of how to write modern framework-dependent React.
➝ The Fetch API is a data-fetching interface to XMLHTTPRequest, which we use to interface with our API. Most modern web applications depend on the Fetch API to build websites without needing a full page refresh. You will see the Fetch API used extensively throughout the repository.
➝ Turbopack is a high-performance bundler optimized to avoid redundant tasks. It is the Rust successor to Webpack, originally designed as a static modern bundler for TypeScript applications.
➝ The Speedy Web Compiler compiles, minifies, and assists with bundling TypeScript files using modern TypeScript features and outputs valid code supported by all major browsers. It is 20x faster than Babel.

All the files

Here are how all of the files are organized, you will need to read the associated documentation but this should get you started.

Creating a well-organized folder structure is crucial for maintaining NextJS projects. Some folders are required by the framework, while others are added according to our own design.

App — part of NextJS

➝ In version 13 of NextJS, a new App Router built on React Server Components was introduced. This supports shared layouts, nested routing, loading states, and, most importantly, enables writing a website that is rendered and cached on the server.

We have included an example of this in our codebase. However, we allow users of our templates to choose whether they want to take advantage of React Server Components or if they prefer React Server Side Rendering instead through the trusted Page Router.

Pages — part of NextJS

➝ Legacy Page-based routing is how most of our template system is implemented because it is backwards compatible and easier for beginners.

The Pages Router was the primary method for creating routes in Next.js before version 13. It uses a file-system router to map each file in the pages directory to a route. For example, if you create a file called my-page-route.jsx, you can visit localhost:10000/my-page-route when you boot up the server.

Common

➝ Traditionally, in projects using other languages or frameworks, a common folder is created to store frequently used functions that multiple files depend on. Recognizing that a well-organized file structure makes it easier to manage and reuse components, we decided to name the folder that stores "standard library" type files "common."

Components

➝ React components that are not intended for use outside of the template are placed here. We have created several components that represent the application and serve as the foundation for the template.

Demos

➝ React components that encapsulate mini applications or examples of our design system in use are placed here. While we prefer that you implement your own demos, you can reference these as examples of how we used the design system components.

System

➝ React components that we encourage everyone to use, remix, redesign, and reimplement are all in this folder. When people fork the template, we hope that everything here is useful and saves time in building their own applications.

Every React component we write uses SCSS for styles. This makes it easier for those not from a JavaScript/TypeScript background to handle styles. We use CSS Modules to scope the styles by creating unique class names at build time, so you don't have to worry about collisions. This approach simplifies sharing and collaboration.

Modules

➝ We are extremely careful when considering dependencies. If there are functions we can cherry-pick from NPM modules and include directly in this folder, we prefer to do that. This approach minimizes the risk of vulnerabilities and reduces the attention cost associated with managing external dependencies.

We believe developers should lean towards creating self-contained projects with more included dependencies (though not all). This practice helps you fix bugs, understand your code better, and reduce what your NextJS application depends on. Older projects, where maintainers have moved on, pose a growing risk to all applications.

Public — part of NextJS

➝ The public folder in NextJS serves static assets, including images, stylesheets, and other necessary files for our application. These assets are accessible from the root URL, making them easy to reference in the project. However, it is better to use a CDN for these assets.

The structure of a React component

This is how our team writes React components

import styles from '@components/Example.module.scss';

import * as React from 'react';

export default function Example(props) {
  return (
    <div className={styles.root}>
      Hello Component
    </div>
  );
}

.root {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

➝ React function components are used throughout.
➝ Each component follows a consistent structure for importing CSS modules.

The structure of a NextJS page

This is how our team writes NextJS Page Router files:

import * as React from 'react';
import * as Server from '@common/server';
import * as Utilities from '@common/utilities';

import GlobalModalManager from '@system/modals/GlobalModalManager';
import KeyHeader from '@system/KeyHeader';
import Page from '@components/Page';

function Example(props) {
  const [key, setKey] = React.useState<string>(props.sessionKey);

  return (
    <Page
      title="wireframes.internet.dev ➝ EXAMPLE"
      description="A lightweight website template to test our design system. You can view this template on GitHub and see how we write websites."
      url="https://wireframes.internet.dev/example-file"
    >
      <KeyHeader onInputChange={setKey} value={key} />
      Hello World
      <GlobalModalManager viewer={props.viewer} />
    </Page>
  );
}

export async function getServerSideProps(context) {
  const { sessionKey, viewer } = await Server.setup(context);

  return {
    props: { sessionKey, viewer },
  };
}

export default Example;

➝ If you copy and paste this code into a file named example-file.jsx and place it in the pages folder as mentioned above, you will be able to visit localhost:10000/example-file in your browser and see the words "Hello World".
➝ Imports are alphabetized.
➝ Prettier is used as an IDE plugin to catch small errors.
➝ A <Page /> component helps handle SEO.
➝ The <KeyHeader /> allows users to plug in their API key to try out features. (More about our API later)
➝ The <GlobalModalManager /> allows for modals to be rendered anywhere.