NextJs Boilerplate

The purpose of this repo is to accelerate startup time when creating a new NextJs app.

Contents

• Getting Started
• Directory Structure
• Features
• Libraries
• Scripts
• IDE Configurations
• Committing Changes

Getting Started

NOTE: this project locks node to a specific version in support of azure static web apps.

Consider using nvm to help manage multiple versions of node.

First, create an .env file with the following:

#APPLICATIONINSIGHTS_CONNECTION_STRING=visit-azure-portal
#NEXT_PUBLIC_API_MOCKING=enabled
NEXT_PUBLIC_API_MOCKING=disabled

# setup NextAuth - https://next-auth.js.org/configuration/options#secret
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=hUZffSRxfqTsXF/08mFxO/T1p0pq2c5pXuZQ82CkSAU=

GITHUB_ID=visit-https://github.com/settings/applications/1778388
GITHUB_SECRET=visit-https://github.com/settings/applications/1778388

Next, install packages:

npm install

Finally, run the development server:

npm run dev

Open http://localhost:3000 with your browser to start.

Directory Structure

📦 src
┣ 📂 __tests__               # tests for pages
┃ ┗ 📜 index.test.tsx
┣ 📂 components              # components used within the app
┃ ┗ 📜 Posts.tsx
┣ 📂 Features                # feature components
┃ ┗ 📂 Home
┃   ┣ 📜 Home.tsx
┃   ┗ 📜 index.tsx
┣ 📂 context                 # application context providers
┃ ┗ 📜 AppState.tsx
┣ 📂 core                    # non-feature related core services
┃ ┣ 📂 msw                   # msw used for mocking http requests
┃ ┃ ┣ 📂 seed
┃ ┃ ┃ ┣ 📜 seedHealth.js
┃ ┃ ┃ ┣ 📜 seedPosts.js
┃ ┃ ┃ ┗ 📜 seedStyleMedia.js
┃ ┃ ┣ 📜 handlers.js
┃ ┃ ┗ 📜 browser.js
┃ ┃ ┗ 📜 server.js
┃ ┗ 📜 test.utils.tsx
┣ 📂 hooks                   # hooks used within the app
┃ ┣ 📂 __tests__
┃ ┃ ┗ 📜 usePosts.test.ts
┃ ┗ 📜 usePosts.ts
┣ 📂 pages                   # pages directory - drives navigation
┃ ┣ 📂 api
┃ ┃ ┗ 📜 posts.ts
┃ ┣ 📜 _app.tsx
┃ ┗ 📜 index.tsx
┗ 📂 services                # feature-related services
┃ ┣ 📂 __tests__
┃ ┃ ┗ 📜 postsService.test.ts
┃ ┗ 📜 postsService.ts

Features

The setup and configuration includes a number of opinionated best-practices in attempt to keep the code clean, safe, and free of bugs.

Code is formatted and linted with each save, if configured, or at least before each commit with the help of husky.

Tests are configured for both unit and integration tests. Unit tests are performed with jest where msw helps avoid mocking http requests, both server and client, which allows for easier integration tests.

Libraries

Application	Description
react	react framework
nextJs	nextjs framework
typescript	Enabling typescript
react-query	Data-fetching library

Static-code Analysis	Description
eslint	Helps identify code issues
prettier	code formatting tool

Testing	Description
jest-junit	Testing Library
msw	Used to intercept and mock http requests
testing-library-react	Helper for UI component tests
jest-html-reporters	Test reporter for visualizing tests

Git Hooks	Description
husky	Creates sharable git-commit hooks
lint-staged	Ensure code is linted before committing to branch
validate-branch-name	Ensures a branch is created before committing to master/main

Library updates

To more-easily update packages, use:

# first, install
npm install -g npm-check-updates

# use ncu
ncu --interactive --format group

Scripts

Unit tests

npm run test    # runs all tests, creating test report

npm run test:open    # opens the test report

npm run test:cover    # runs all tests, creating coverage report

npm run test:cover:open    # opens the coverage report

End-to-end (e2e)

npm run test:e2e    # within the cli, runs end-to-end (e2e) tests

npm run test:e2e:open    # visualize end-to-end (e2e) tests

npm run test:e2e:verify    # validates end-to-end (e2e) tests ability to run

npm run test:e2e:ci    # runs end-to-end (e2e) tests for continuous integration (ci) pipeline

npm run test:e2e:report    # opens html report from end-to-end (e2e) test results

Static code analysis

npm run lint    # runs lint check, produces report

npm run lint:fix    # runs lint and fixes, produces report

Utility scripts

npm run prepare   # installs husky hook - this lints the app before each commit

npm run format   # run code format check

npm run format:fix   # run fix code formatting

npm run pre-commit   # this is ran prior to a git commit - runs lint and checks branch name

IDE-configuration

VS Code

The .vscode directory is checked into this repo and serves to share common settings and defaults.

Recommended Extensions are configured, be sure to install.

Setting	Description
eslint.validate	Validate and fixes eslint errors. This also fixes prettier issues
typescript.suggest.paths	Turned off to enable correct usage within auto-rename-tag

Extension	Description
code-spell-checker	checks spelling errors withing the code
vscode-icons	Directory icons
vscode-jest	Helps renaming tags
auto-rename-tag	Helps renaming tags
vscode-eslint	Integrate with lint rules

Snippets

// entering: desc
describe('', () => {});

// entering: it
it('should ', () => {
  // arrange
  // act
  // assert
});

// entering: ita
it('should ', async () => {
  // arrange
  // act
  // assert
});

// entering: func
export default function () {}

// entering: hook
export default function use() {}

Webstorm

The .idea directory is checked into this repo and serves to share common run configurations

Setting	Description
All Tests	Execute and watch all tests
Dev	Run application

Committing Changes

Husky makes git hooks sharable within a project while also ensuring code conventions are enforced. The hook is installed during npm install and should require no further setup.

Husky pre-commit is configured to run the npm task pre-commit which does the following:

• Avoid commits to master/main
• Format staged code
• Lint staged code

Should the need arise to ignore the hook, manually commit using --no-verify

# Example
git commit -m "commit message" --no-verify