What is necessary before cloning this repository?
- Make sure to install Docker Desktop
- Node Version Manager needs to be installed
- This project also works with pnpm package manager
Note: to install the above information, please see the Instructions on your preferred Operating system
- Setting up Locally
- Instructions for Linux
- Instructions for Windows
- Instructions for Mac
- Node Version Manager
- pnpm Package Manager
- Once you have installed what is required for your operating system, come back to this space
- using either http or ssh to clone your repo
- git clone https://github.com/douglas86/nextjs-template.git
- git clone git@github.com:douglas86/nextjs-template.git
- This project uses node version 22
- Which can be seen in the package.json under the engines object
- Please make sure that nvm is installed and using node version 22
- To see if you have the correct node version, run $ node --version
- If it does not say 22
- Then using nvm run the following commands:
- $ nvm install 22
- $ nvm use 22
- $ nvm default 22: this command will make 22 the new default node version
- Once that is done, make sure that it is the correct node version run: $ node --version
- The next step would be to set up all environment variables
- create a file .env in the root directory of your project
- on the same level as docker-compose.yaml
DATABASE_URL environment variable
- To get the DATABASE_URL follow the following pattern
- postgresql://username:password@localhost:5432/database?schema=public
- to get this information, look at the docker-compose.yaml file
- under the database service
- POSTGRES_USER: username
- POSTGRES_PASSWORD: password
- POSTGRES_DB: database
- this is for local development
NEXT_APP_GOOGLE_CLIENT_ID and NEXT_APP_GOOGLE_SECRET_KEY environment variable
- Set up Google Authentication
- This needs to be set up in the Google developer console
- Call this new Project based on the project that you are creating
- NEXT_APP_GOOGLE_CLIENT_ID: client id
- NEXT_APP_GOOGLE_SECRET_KEY: secret key
- copy and paste it in the environment variable
JWT_SECRET, DATA_ENCRYPTION_SECRET, NEXTAUTH_SECRET_IV environment variable
- These secret keys need to be generated
- Use the following command $ openssl rand -base64 32
- that should then give you a string that is necessary for .env file
- if you are using windows, make sure to use wsl
- once generated, place it in your environment variable file
- you can use the same generated key for all the environment variable
- during local development
- But if this is going to production, please create different keys for each one
- it will help improve security
NEXTAUTH_ALGORITHM environment variable
- The project uses an algorithm for decrypting and encrypting data
- use an algorithm of aes-256-cbc
- NEXTAUTH_ALGORITHM: algorithm key
NEXTAUTH_URL environment variable
- this is the url that you are using for this project
- NEXTAUTH_URL: http://localhost:3000
Note: make sure that all environment variables are in quotes
- Once nvm has been setup for node version 22
- install pnpm globally; this is the package manager that I am using for this project
- $ npm install -g pnpm: this is the command to install pnpm globally
- To start this project, make sure that Docker Desktop is up and running
- and run the following command: $ pnpm dev
- this will install and run the project,
- at the same time, it will also run the migrations for the databases
- once that running process has finished, open up a browser
- go to localhost:3000
Note: "$" symbol in front is not part of the command it is to show that it is a command meant for the terminal
- Install docker desktop from the following link
- If you are needing additional assistance, go to the credits section for additional information
- Once docker desktop has been installed then install nvm see instructions below
- This Project uses pnpm as its package manager
- To install pnpm globally, run the following command: $ npm install -g pnpm
Note: "$" symbol in front is not part of the command it is to show that it is a command meant for the terminal
- Install docker desktop from the following link
- Install wsl this will help with giving you Linux Superpowers on a Windows Machine
- Once wsl has been installed, see instructions on installing nvm
- Install docker desktop from the following link
I haven't been able to test on a MacBook Yet But, strictly speaking, the setup process should be the same as Linux
- To install node version manager with curl, run the following command
- $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
- then restart the terminal
- to verify that it worked, run the following command
- $ nvm --version
- Once you have installed nvm, go back to the installing instructions for your Operating System
Note: "$" symbol in front is not part of the command it is to show that it is a command meant for the terminal
Commands that can be used with NVM:
- nvm --version: show the version of nvm
- nvm install 22: install node version 22
- nvm use 22: use node version 22—when you run this command it is only available for the current session
- nvm default 22: sets node version 22 as the default version
- nvm list: will show you all node versions that you have on your system
Note: To get the latest nvm script click here
To install pnpm run the following command: $ npm install -g pnpm
Commands that can be used with PNPM:
- pnpm script: this will run the script that is defined in package.json, a script is the name of the script
- pnpm store prune: this will remove all node modules that are not attached to any projects if you delete node_modules and pnpm lock file run this command after wards
- pnpm install: install all packages from package.json
- pnpm add package: adds the package that you want to install
- pnpm exec prisma generate: this will generate the data in your prisma schema
- pnpm exec prisma migrate dev: this will migrate the database
Note: pnpm uses symlinks for all node packages, which in theory is supposed to make it faster for execution and storage space
Note: If you are using windows, please use PowerShell to run pnpm as for some reason wsl didn't want to work in this regard
This project has the following features
-
cypress for testing
-
prisma orm for database management
-
tailwind for styling all of my components
-
swagger ui for documenting all endpoints
-
I have also setup custom hooks: useFetch, useScroll, useAppContext
-
I have also setup scripts to make it easier to run certain commands
Docker
- To run the docker script type $ pnpm docker
- Please make sure that Docker desktop is up and running before running this script
- This will run three commands:
- $ pnpm store prune
- $ pnpm install
- $ docker-compose up
- it will first remove all dead packages from pnpm store
- It will then install all packages to pnpm store
- it will then start the docker daemon tool
Prisma
- To run prisma script type $ pnpm prisma
- This will run prisma studio
- Prisma Studio to a GUI for Prisma ORM
- It is used to visualize your data in the database
- It opens in a new browser tab
Cypress
- To run cypress script type $ pnpm cypress
- Cypress is a test framework for automatically testing the UI/UX of your website
Introduction: This hook is going to be used to fetch data from the server
- When fetching data from the server, pass the endpoint of the server that you are wanting data from
- For example, you can pass it the endpoint api/user
- this will fetch data from that endpoint
- but you don't need to say api in front of it
- call the endpoint user
- look at the image down below for a better example
Introduction: This hook uses infinite scroll to fetch data from the server
- I have created a custom hook called useScroll
- import it at the top of your file
- destructure: issues, loadMoreRef, isLoadingMore, isReachingEnd from custom hook
- There is one required value and an optional value to pass into the hook
- The required parameter is the url that you want to get from
- The optional parameter is how many documents you want to fetch at a time
- This optional parameter is defaulted to 10 documents
- The data can then be mapped
- A div needs to be created as a placeholder for the ref (shown on line 31)
- The next one is isLoadingMore which is used to see if more data is to come
- The next one is isReachingEnd for telling you when the end is near
Introduction: This hook is used to fetch and post data to the state store
- There are five objects that are declared for the state store
- state, dispatch, user, data, forms
- state—this is everything that is stored in your state store
- dispatch - this is when you want to post something to the state store
- user, data, forms—these are reduced functions that were defined in the context directory
Fetching data from state store?
- When the app loads, I fetch data for the current logged-in user
- To use this data, you only need to structure it
- Once data has been fetched, you can display it with ease
- The same thing goes for the other reduced functions
- The data reduced function is for all other data that you want to fetch and use
- The forms reduced function are to handle all form data
- Only form data that you want to post to your endpoint
Posting data to your endpoint?
- To post data to your endpoints destructure dispatch from state
- When posting data to state store pass a maximum of two objects to dispatch
- type and payload
- type is what case inside the switch statement you want to use
- payload is the data that you are wanting to post
- You can see the type if you look at the user reducer function
- To use swagger UI type /swagger into the address bar
- Wait about two to three seconds for Next.js to cache the data
- All data for swagger is stored in swagger.yaml file
- under public directory
We will be using Git Flow as Our Branching Strategy
- main: The Production branch. Only stable, tested code is merged here
- develop: This is an integration branch for all new features
- release: This branch is for all final testing before develop gets merged to main
- feat/[feature-name]: All new features get done from here. Once completed gets merged to develop and branch gets deleted
- hotfix/[issue-name]: Used for urgent fixes. Created from main then merged into main and develop branch
- docs/[documentation-name]: Used for updating the documentation. Once completed gets merged to release branch
- bug/[bugfix-name]: Used to fix final bugs on the release branch. Created from release. Once completed get merged to release branch.
Note: for this project I have added two additional branch names, bug and docs
This repository has got certain branch protection rules applied
- This Rule helps to prevent direct pushes
- To main, develop or release branch
- If you try to do direct pushes, it will reject your push
- This rule will see if the branch naming convention is correct
- In other words, only if the branch name is main, develop, release, feat, hotfix, bug, docs
- If you haven't created the correct naming convention, it will reject your push to git
- This rule will check if the PR is from an allowed branch
- For example, if you want to create a PR and you try to merge it with main
- It will only allow hotfix/* and develop branches into main
There are three different criteria that fall into this category:
- only allow PR's from hotfix/* and develop into main
- only allow PR's from feat/* and release into main
- only allow PR's from bug/* and docs/* into release
- Description of atomic design
- Atoms: first stage
- Molecules: second stage
- Organisms: third stage
- Templates: forth stage
- Pages: fifth stage
- Atomic design is a methodology composed of five distinct stages working together
- to create interface design systems in a more deliberate and hierarchical manner.
- The five stages of atomic design are:
- Atoms
- Molecules
- Organisms
- Templates
- Pages
- Atomic design is not a linear process,
- but rather a mental model to help us think of our user interface
- as both a cohesive whole and a collection of parts at the same time.
- Each of the five stages plays a key role in the hierarchy of our interface
- design systems. Let's dive into each stage in a bit more detail.
- If atoms are the basic building block of matter,
- then the atoms of our interfaces serve as the foundational building blocks
- that comprises all our user interfaces.
- These atoms include basic HTML elements
- like form labels, inputs, buttons, and others
- that can't be broken down any further without ceasing to be functional.
-
In chemistry, molecules are groups of atoms bonded together
-
that takes on distinct new properties.
-
For instance, water molecules and hydrogen peroxide molecules have their own
-
unique properties and behave quite differently,
-
even though they're made up of the same atomic elements (hydrogen and oxygen)
-
In interfaces, molecules are relatively simple groups of UI elements
-
functioning together as a unit. For example, a form
-
label, search input, and button can join together to create a
-
search form molecule.
-
Organisms are relatively complex UI components composed of
-
groups of molecules and/or atoms and/or other organisms.
-
These organisms form distinct sections of an interface.
-
A search form can often be found in the header of many web experiences,
-
so let's put that search form molecule into the context of a header organism.
-
The header forms a standalone section of an interface,
-
even though it contains several smaller pieces of interface
-
with their own unique properties and functionality.
-
Organisms can consist of similar or different molecule types.
-
A header organism might consist of dissimilar elements
-
such as a logo image, primary navigation list, and search form.
-
We see these types of organisms on almost every website we visit.
- Templates are page-level objects that place components
- into a layout and articulate the design's underlying content structure.
- To build on our previous example, we can take the header
- organism and apply it to a homepage template.
-
This homepage template displays all the necessary page
-
components functioning together, which provides context for
-
these are relatively abstract molecules and organisms.
-
When crafting an effective design system,
-
it's critical to demonstrate how components look and function
-
together in the context of a layout
-
to prove, the parts add up to a well-functioning whole.
-
By defining a page's skeleton, we're able to create a system
-
that can account for a variety of dynamic content,
-
all while providing the necessary guardrails for the types of content
-
that populates certain design patterns.
-
For example, the homepage template for Time Inc.
-
shows a few key parts in action while also demonstrating
-
content structure regarding image sizes and character length
- Pages are specific instances of templates that show what a UI looks like
- with real representative content in place.
- Building on our previous example, we can take the homepage template
- and pour representative text, images, and media into the template
- to show real content in action.
- The page stage is the most concrete stage of atomic design,
- and it's important for some rather obvious reasons.
- After all, this is what users will see and interact with
- when they visit your experience.
- This is what your stakeholders will sign off.
- And this is where you see all those components coming together to form
- a beautiful and functional user interface.
Explain the Problem?
- Whenever I try to log in for the first time
- I get this error
- I think this is a problem with trying to decrypt data
- This will be an issue with session object in NextAuth endpoint
Explain the Problem?
- I keep on getting a session error with Next Auth
- This Problem happens with JWT tokens
- When ever I am logged in with Google authentication
- This Problem comes from the session object in Next Auth
- For this project, JWT tokens are not being used
- I am rather storing session token in db
- which are more secure
- YouTube tutorial on setting up docker desktop if you still need assistance
- For an interactive tutorial for Next.js
- You are wanting to see Next.js documentation
- This article helps me with encrypting and decrypting data
- Explanation of the atomic design was taken from here