next js rapid starter

Contains a skeleton for rapidly standing up sites in a docker container running next.js.

Features

• rendering

  • client side rendering with react
  • server side rendering
  • build time static generation
  • auto tree shaking and building
  • auto polyfilling only in required browsers

• routing

  • built in file based routing with param support

• api

  • built in api support

• styling

  • tailwind
  • Built in support for cssmodules/sass/scss

• devtools

  • Built with typescript
  • Full hot-reloading support. Just save your changes to see them reflected on the site.
  • Linting support with eslint + prettier
  • lint on git commit via husky
  • vscode debugger preconfigured for server and client-side
  • relevent vscode extensions auto-recommended
  • built in bundle size analysis

• security

  • out of the box security headers. E.g csp
  • license check on Pull Request
  • checks for critical security issues on Pull Request

• logging

  • pre-configured to output json structured logs
  • sends client-side logs to the server
  • configurable log level via env vars

• building

  • docker build already setup
  • Optional cloudbuild steps for a Pull request already configured
  • Optional export mode that allows the site to be simply hosted from a directory in bucket

• testing

  • testing already setup for
    • pages
    • components
    • arbitrary typescript
    • api routes
  • snapshot test support
  • tests ran on Pull Request
  • test coverage reported
  • tests support watch mode

• Internationalisation support

  • built on next-i18next
  • per language routing
  • browser language awareness
  • supports multiple translation files per language
  • language can be selected based on domain or path

  See the docs directory for more information

Local development

Requirements

• Node.js 18.x or higher
• Pnpm

Recommended tools

• visual studio code

  • editor config extension
  • jest extension
  • debugger for chrome extension
  • eslint extension
  • prettier extension

• If you are running in windows then use the new terminal

Running locally

You can then run the app by:

• running pnpm install to install the packages
• running pnpm start to start the app in local development mode
• visiting http://localhost:3000

Available commands

• pnpm start - start the app running locally in dev mode
• pnpm test - run the tests
• pnpm test:watch - run the tests in watch mode
• pnpm test:ci - run the tests for ci/cd + generate a coverage report
• pnpm lint - lint the codebase, applying fixes where possible
• pnpm lint:ci - lint the codebase, erroring out if code does not meet requirements
• pnpm analyze - show what takes up the space in the bundle
• pnpm security:licenses - show what licenses are in use, failing on GPL
• pnpm security:packages - show any security issues with packages, failing on critical issues
• pnpm build - build the app ready for production
• pnpm start:production - run the built package

How do I get started making changes?

There's a lot of code here, it can be a little intimidating. But to start with just concentrate on making your pages in /pages and creating your components in /components. If you are just building a normal react app you can build everything just using those areas.

Clearing out the example code

• You can delete all the files in /pages apart from _app.ts and document.ts.
• You can delete all the components (*.tsx) in /src except for the bits under the /src/layout directory. You can edit the contents of the /src/layout directory however you like but just bear in mind that right now the Layout.tsx file references the other layout components.
• If you dont need a local api you can delete the entire /pages/api and src/api folders.

Documentation

The docs folder contains more information about the project

• code structure - covers the general layout of the code
• debugging - how to debug the client and server side code
• deploying - how to deploy to dev/qa/stage and production
• logging - configuring log levels
• testing - how to run tests
• styling - styling using tailwind
• api - Details about the api endpoints.
• linting - When the linter runs.
• monitoring - How to check the health of the system, where to look if something breaks

How do I add "feature X"

This repo is a base to build on but fundamentally it is just a next.js project. Next.js iself has great examples of how to add various features available here and these will work just the same in this project.

Future enhancements

• Testing the running site end-to-end using playwright
• Use the next image component to automatically resize images at build time and serve them using the most efficient mechanism
• An example of use getStaticPaths to generate multiple pages at build time