Overnext - Overly Opinionated Next.js Boilerplate

Tooling

Versions

Metrics

Approach

• DX first
  • the foundation
• Integrations second
  • db/cms
  • Third-party services
• UI third
  • all screens: from watch-face to wide screen, not just mobile/desktop
  • the new responsive
• UX last
  • features & content

This is more about priorities than about a temporal order.

Guiding Principles

• automate it ™
• optimize it, do it cheap
• go vanilla until good reasons to not
• test & lint it, to catch bugs early
• manage tech dept

DX

• pnpm package manager

• automation, inspirations

• conformity, inspirations

• standard-version for release versioning and changlog creation

• browserlist for browser compatibility

  • autoprefixer
  • eslint-plugin-compat
• enable expiring ToDo's (`eslint-plugin-unicorn`)

  • Expire after a specific date: [YYYY-MM-DD] to define a UTC due date in the ISO 8601 format
  • Expire when your package (package.json) reaches a specific version: [>1] or [>=2]. No whitespace.
  • Expire when a package.json engines property reaches a specific version: [engine:node@>8] or [engine:node@>=8], only node engine is supported. No whitespace.
  • Expire when you install/uninstall a specific package: use [+package] or [-package] to expire. No whitespace.
  • Expire when a package reaches a specific version: use [package@>1] or [package@>=2]. No whitespace.

Tips

• use volta for toolchain management (hoping for pnpm support), see: install guide
• use eslint_d to speed up ESLint, volta install eslint_d
• use pnpm completion via pnpm install-completion
• create recommended repository files via cgx
• create README.md integrate via README.so template

Commit Style

• Conventional Commits convention

  • Commitizen CLI helper

    Show commit types

    • a11y: Accessibility
    • build: Changes that affect the build tooling (example scopes: webpack, TypeScript, pnpm)
    • chore: Other changes that don't modify src or test files
    • ci: Changes to the CI configuration files and scripts (example scopes: GitHub Actions, BrowserStack)
    • cx: Customer Experience
    • deps: Managing dependencies
    • docs: Documentation only changes
    • dx: All things about improving developer experience
    • feat: A new feature
    • fix: A bugfix
    • i18n: Internationalization
    • perf: A code change that improves performance
    • refactor: A code change that neither fixes a bug nor adds a feature
    • revert: Reverts a previous commit
    • style: Changes that do not affect the meaning of the code (whitespace, formatting, missing semi-colons, etc)
    • test: Adding missing tests or correcting existing tests
    • ui: CSS and layout
    • ux: User Experience
    • wip: work in progress

  • semantic-pull-requests GitHub app

Scripts

To print a description of the scripts run pnpm run info

dev: Start next app in dev mode
debug: Start node debugger
build: Build the app
start: Start server to serve the local app build
serve: Build app and start server
servex: Build & run app on public URL
test: Run unit and integration tests once
test:ci: Run jest tests on CI, will re-add cypress later again
test:jest: Run jest tests and update screenshots
test:cy: Open cypress test runner (needs a running app server)
e2e:watch: Start dev server, open cypress and watch
e2e: Build & serve app, then run cypress once
format: Format source code and fix issues
lint: Lint source code
lint:fix: Use deamon to lint source code and fix issues
lint:html: Run html-validate on generated static output files
lint:css: Run stylelint on source code to lint CSS
checklinks: Test integrity of hyperlinks in the build files
checklinks:server: Test integrity of hyperlinks on the local server
validate: Validate source code and output files
validate:src: Format, lint, type-check & unit test the app
validate:out: Build app, run integration tests, check links & validate generated html
build:analyze: Build app and output bundle analyzer diagrams
build:size: build app and measure loading performance
size: Run size-limit
size:why: Run size-limit and open statoscope report in browser
audit:fix: Check vulnerabilities in production package and try to fix them
find:unused: Find unused files
build:ssr: used on CI for 'compressed size' action
cz: Make new commit
release: Prepare a new release
docs: Generate typedoc docs
info: Display info about the scripts
stylelint-check: Check stylelint for rules conflicting prettier

Code Style

• React Strict Mode enabled in development
  • prop-types (for runtime type checking) -> discarded, see reasons
  • not using defaultProps on function components because deprecation incoming
• TypeScript (for compile time type checking)
  • typesync for find dependency typings
  • TSDoc docstrings to generate typedoc documentation
• Prettier for code formatting
• EditorConfig

Linter / A11y

• ESLint

  • most core rules are enabled

  • eslint-config-prettier, turns off all rules that are unnecessary or conflict with Prettier

  • typescript-eslint, rules

  • eslint-plugin-unicorn, 77 rules

  • eslint-plugin-react, rules

  • eslint-plugin-react-hooks

  • eslint-plugin-promise, 12/14 rules

  • eslint-plugin-array-func, rules

  • eslint-plugin-jsx-a11y, rules

  • eslint-plugin-compat, works with browserslist

  • eslint-plugin-import, 43 rules

    • typescript-eslint-language-service, adds TypeScript support for eslint-plugin-import

  • eslint-plugin-next, 12 rules

  • eslint-plugin-sonarjs, 25 rules

  • eslint-plugin-sort-keys-fix, because core can't autofix object keys

  • eslint-plugin-tsdoc

  • eslint-plugin-eslint-comments

  • eslint-plugin-cypress

  • eslint-plugin-jest

  • eslint-plugin-jest-dom

  • eslint-plugin-jest-formatting

• stylelint for CSS

  • stylelint-config-standard configuration
  • stylelint-config-idiomatic-order configuration
  • stylelint-config-prettier configuration, to integrate with prettier
  • stylelint-scss plugin

• textlint for text, collection of rules

  • textlint-plugin-jsx for JSX and TSX support
  • textlint-rule-terminology to check and fix terms, brands and technologies spelling

• husky for hooks

• git-format-staged, to format staged files (surprise), reasons

• axe-core/react

Potentially interesting

• eslint-plugin-optimize-regex, there are even more regular expression plugins
• eslint-plugin-testing-library
• eslint-plugin-i18n-json

Tech Stack

• next.js, who would have thought
• production deployment (& a test branch with another setup) with preact, btw inferno is not compatible with nextjs
• Sentry for error monitoring
• FaunaDB
• WIP: sanity
• TODO: React Query

Afternext

• vite with vite-plugin-ssr
• solid.js
• svelte

Next.js Configuration

Features in use

• src Directory
• Custom App
• Custom Document
• Custom Error Pages
• Absolute imports and module path aliases, so far no need for path aliases
• Internationalized Routing
• AMP Support, but maybe not for long
• Measuring performance
• Security Headers, gets an 'A' on securityheaders.com

Plugins & Helper

• compose plugins
• webpack bundle analyzer
• next-pwa
  • for PWA support via workbox
  • see documentation
• next-sitemap
• next-seo, for MetaTags, OpenGraph & JsonLD
• next-themes, for dark-mode
• persistend layout
• next-unused
• integrate @babel/preset-env with browserslist currently not possible, can only use targets option to set targeted browser

Styling

...all still unclear atm...

• Stage 1: site should be useable without any CSS

• Stage 2: site should look OK with only classless CSS

• Stage 3: some kind of CSS framework, no CSS in JS

• keep it simple

• make use of modern-normalize -> is part of tailwind

• Tailwind CSS - really unsure about it, esp. after reading this

• first, find some nice minimal/classless CSS framework

  • shoelace
  • em dash

• ToDo: autoprefixer, issue on next.js side

• ToDo: integrate PostCSS Preset Env with next.js PostCss Config

• ToDo: integrate lazysizes, with native loading

Testing

• Jest
  • react-testing-library
• Cypress
  • Code Coverage via istanbul and nyc, bon voyage
  • Dashboard
  • GitHub Integration
  • cypress-watch-and-reload
  • ToDo: if I want to run headless cypress in watch mode
• ToDo: integrate Sentry TestKit, to intercept error reporting in tests

CI

GitHub Actions

• Skip Duplicate Actions
• create-pull-request, creates PR's for new branches
• Labeler: adds labels to PR's based on the changed files
• dependency-version-badge: update version badges in README
• basic: runs linters, tests and build
• compressed-size: checks the size of the bundled files and adds a comment in the PR
• size-limit for load time performance tracking
• eslint-plus-action, runs ESLint and prints a summary in the PR
• Super-Linter
• Lighthouse on Vercel: Runs a Lighthouse Audit on the Vercel Preview URL
• WIP: auto-push-css, needs PROJECT_WALLACE_TOKEN set in repository Env Secrets

WIP Security Audits

• ShiftLeft Code Scanning
• CorrelatedLabs/detect-secrets-action
• RobertFischer/detect-secrets-action, uses Yelp's detect-secrets

Audits & Service Dashboards

• Lighthouse on vercel

• Sentry

• Quickmetrics Dashboard

  • to track Web Vitals
  • how-to

• Sonarcloud Dashboard

  • needs SONAR_TOKEN env var in GitHub

• LGTM Dashboard

• Code Inspector

• Cypress Dashboard

• Fossa Dashboard

  • needs FOSSA_API_KEY env var in GitHub

• Renovate Dashboard for dependency management

• Vercel Dashboard

• Netlify Dashboard

• Dareboost, free version has 5 analyses per month

• Project Wallace for CSS monitoring

Installation

see CONTRIBUTING

Deployment

• Documentation
• Vercel
  • for pnpm:
    • override "Install Command":
      • npx pnpm i -P (skips dev dependencies) -> this has issues
      • rm -rf node_modules && npx pnpm i -P
      • npx pnpm i -P --shamefully-hoist
      • npx pnpm i -P --store=node_modules/.pnpm-store --shamefully-hoist
    • override "Build Command":
      • pnpm run build (vercel will use yarn otherwise)
  • vercelignore to only upload neccessary files
  • Sentry Integration
• Netlify
  • Caveats:
    • "Redirects and rewrites using next.config.js aren’t currently supported for Next.js sites on Netlify."
    • Locale Detection not working
  • netlify.toml
  • asset post processing
  • skip deployments without relevant changes
  • netlify plugins
    • netlify-plugin-cypress
    • netlify-plugin-html-validate, uses html-validate
    • netlify-plugin-checklinks, uses hyperlink
    • netlify-plugin-a11y, uses pa11y
    • Sentry Netlify build plugin
• AWS Amplify
• Maybe ToDo: Azure Pipelines
• tried Cloudflare Pages but only works for static pages via next export which in turn doesn't support i18n

Demo

• Vercel
• Netlify

Monitoring

• Sentry, via @sentry/nextjs, docs, which is a wrapper around
  • Sentry for React, docs, for the app frontend monitoring
  • Sentry for Node.js, docs, for server monitoring
  • SentryWebpackPlugin, to load client & server monitoring & for source map upload
    • uses sentry-cli under the hood
• Speedlify

Documentation

ToDo Documentation

Learnings

prop-types

Intially I wanted to use prop-types because of the reasons given in those articles:

• TypeScript and React: Prop Types - Blogpost by Stefan Baumgartner
• PropTypes in a TypeScript React Application - Anwer on Stack Overflow
• Notes on TypeScript: Inferring React PropTypes - Guide on dev.to

When I actually started using them I had some problems:

• to be able to extend the function object I had to use React.FC because otherwise TypeScript prevents this, but:
• I don't want to use React.FC for these reasons,
  • especially I don't want to close the door for going Preact
• also prop-types itself seem to have an unclear future

I might still use prop-types in case I encounter a situation where I get much benefit from the runtime type checking, but then I would only use it for this specific case.

TypeScript Barrel

Using an index.ts file to bundle multiple submodules is called 'Barreling'. This can cause circular dependency issues as it happened to me because I was using the env.config inside of seo.config. Also it might affect webpack's ability to chunk the code.

• Gitbook on barrel

Linter

Initially I used Prettier-Standard which included

• Standard
• PrettierX because I thought it's a great idea to not waste time for config etc. But the tool hasn't received any maintenance for almost a year and I already had to add workarounds. Being interested in linting in general I also had issues with clean extensibility of my ESLint config and it wasn't completely clear to me what really runs as part of prettier-standard.

I also considerd other bundles like:

• XO which would have been my first choice because it includes unicorn
• Canonical

but they all have stuff included I don't need and other stuff is missing which I want so I decided to go vanilla eslint and do my config by hand to have max control over everything and Less dependencies.

Hosting

There are a few differences between Vercel & Netlify.

• sass module can be a devDependency on Netlify, but must be a (production) dependency on Vercel
• i18n routing: on Vercel the user is redirected to the browser detected language by default, but not on Netlify

Setup

ToDo

API Reference

ToDo link to API Docs

Roadmap

• integrate Sanity
• integrate React Query
• integrate React Hook Form
• integrate ajv

Optimizations

Credits

...where credits due, thanks to @bahmutov, @elliottsj, Stefan Baumgartner, @ferlopezm94,@iamvishnusankar, @pacocoursey, @thomaseizinger, @sindresorhus and all the others whom I copied code from!

Related

• Next Right Now
  • next-right-now, flexible production-grade boilerplate with Next.js
• Next.js with Moxy, a better version of this project
  • next-with-moxy

ToDo

I should use GitHub Issues for this but hey.

• I have Node.js version defined in several places, maybe I can consolidate this
  • .nvmrc
  • .npmrc because pnpm
  • package.json > engine, removed because annoying warning in vercel
  • package.json > volta, for volta
• add SRI
• cypress a11y plugin
• cypress-html-validate plugin
• make use of Project Wallace, still wip
• wdyr vs preact 1
• use ISR - Incremental Static Regeneration ? opinion

Documentation ToDo's

• automate typedoc generation
• maybe apiDoc?, ts-docs-gen?, DocFX?

Project Automation / Labeling Ideas

Issues

• ToDo: zenhub link pr to issue
• ToDo: tag ur it
• ToDo: auto label
• ToDo: issue action
• ToDo: actions comment run

Projects

• ToDo: auto card labeler
• ToDo: project automation plus
• ToDo: move issue to project column
• ToDo: project bot
• ToDo: automate projects

Milestones

• ToDo: create milestone

Branches

• ToDo: create-issue-branch

Pull Requests

• ToDo: PR Labeler
• ToDo: prow GitHub action
• ToDo: task completed checker action

Licenses