1 of 9

Next.js WebApp Starter documentation

Introduction

An up-to-date, reasonably opinionated starter template for Next.js web apps

What is Next.js WebApp Starter?

Next.js WebApp Starter is an up-to-date, reasonably opinionated Next.js starter template. It's bootstrapped with create-next-app, complemented with some icing on top (the reasonably opinionated part).

Note: This is a community-created project and is not affiliated with Vercel or Next.js.

We only cover core Next.js features in our documentation when it's necessary to help explain a Next.js WebApp Starter feature. To learn more about Next.js itself check out .

Features

Next.js WebApp Starter comes with the following features:

It's .
is added as a in the Next.js build chain.
sass library installed to enable Next.js' built-in Sass support.

We're currently in a 0.x iterative release cycle. Check out the version 1.0 roadmap .

Project Goals

The overarching goal of this project is to provide a Next.js starter template that has the following attributes:

Is open-source.
Actively maintained, with all project dependencies kept up to date.
Integrates new core Next.js features as soon as possible after new Next.js versions are released, accompanied by appropriate documentation in this project's official documentation site and, where suitable, in the code.

Who created it?

Next.js WebApp Starter is an open source project started and being maintained by , a full stack software developer from Barbados.

If you would like to donate to my development efforts on this project, you can do so . All sponsors will be recognized in the project README and here in the documentation.

How can I contribute?

Development of this project is being done in the open on GitHub and contributions are welcomed. To learn more about how you can contribute, please read the project's and .

Getting Started

Option 1: Use `create-next-app`

You can use create-next-app to quickly create a new project with this Starter, by running the following command:

Check out the development guides to familiarize yourself with the project's code structure.

Option 2: GitHub's `Use this template` feature

From this project's click the Use this template button to .

There are two branches. The default branch, named release, contains the code for the latest stable release. The other branch, named canary, is the development branch and holds code for the next release. By default you will only get the release branch. If you want your repository to be created with the canary branch as well, make sure to select the Include all branches checkbox in the repository creation form.

Depending on your workflow either clone, or fork and then clone your repository to your local environment and then do the following:

Make sure you have (>= 10.21.0) installed.
Install the dependencies:
Run the Next.js development server:
Open with your browser to run the web app. To specify a port other than 3000 use the

Before you start coding

We ship an opinionated feature set on top of the default app that create-next-app gives you. Check out the to familiarize yourself with the code structure of Next.js WebApp Starter.

Folder Structure

After creation, your project should look like this:

The purpose of each of these files and folders are as follows:

.github

This folder simply contains the project's Contributing Guide.

tests

This folder should contain all tests written. Currently unit tests are provided for each localized version of the template's index page.

config

Stores configuration files for most of the starter template's features:

i18n/config.ts - Used by our react-i18next integration. You should not modify this file to customize the configuration for your app, instead you should modify app.config.ts.
jest/cssTransform.js - Used by our Jest setup to transform .css files.
jest/test-utils.tsx - Loaded by each test file to set up the testing framework before each test.

public

Stores the following image and json assets:

locales - Contains sub-folders for each locale configured for the app, which in turn contain the locale translation files. This is an example of how to configure translation files to leverage i18next's Namespaces feature, more of which you can learn about .
favicon.ico, *.png - favicon and application icon files.

src

This is where the custom components, pages, Context API providers, typings and utility code for the project live.

Non-page components

styles

Stores the app's global CSS and CSS/SCSS module files. Feel free to look around at these files to see how easy it is to leverage the Tailwind CSS support integrated with this starter template. Modify/replace the files to suit the needs of your app.

Development

TypeScript Integration

Next.js WebApp Starter is developed as a TypeScript Next.js app. As such, there are a few things that are worth mentioning.

Page Components

Custom `App`

src/pages/_app.tsx

Next.js WebApp Starter implements the following custom App component:

// import App from "next/app";
import type { AppProps /*, AppContext */ } from "next/app";
import Head from "next/head";
import I18n from "i18n/create-provider";
import App from "components/App";
import "styles/index.css";

function MyApp(props: AppProps) {
  return (
    <>
      <Head>
        <meta
          name="viewport"
          content="minimum-scale=1, initial-scale=1, width=device-width, shrink-to-fit=no, user-scalable=no, viewport-fit=cover"
        />
      </Head>
      <I18n
        requiredNS={props.pageProps.requiredNS}
        lng={props.pageProps.lng}
        lngDict={props.pageProps.lngDict}
      >
        <App {...props} />
      </I18n>
    </>
  );
}

// Only uncomment this method if you have blocking data requirements for
// every single page in your application. This disables the ability to
// perform automatic static optimization, causing every page in your app to
// be server-side rendered.
//
// MyApp.getInitialProps = async (appContext: AppContext) => {
//   // calls page's `getInitialProps` and fills `appProps.pageProps`
//   const appProps = await App.getInitialProps(appContext);

//   return { ...appProps }
// }

export default MyApp;

Let's break down this file.

Misc

Changelog

v0.6.2 (2020-09-11)

Changed

README: Re-ordered Getting Started options ()

v0.6.1 (2020-09-11)

Changed

Uninstalled github-buttons package ()
Updated i18next-http-backend and i18next-http-middleware dependencies ()

v0.6.0 (2020-09-11)

Added

PWA support via next-pwa ()

Changed

Revamped index page layout ()
Updated README, changelog, Code of Conduct and contributing guide () () ()
Updated tests that were broken by new index page layout ()

v0.5.0 (2020-09-06)

Added

Jest and React Testing Library ()
Unit tests for the homepage (including tests for the header and footer components) ()
file to simply site-wide configuration of your Next.js project ()

Changed

Refactor: Moved i18n and seo config files to config/ folder ()
README: Updated Features section ()

v0.4.0 (2020-09-03)

Added

Integrated Next SEO plugin library ()

Fixed

Refactor: Replaced router.push calls in src/lib/utils.ts and src/pages/index.tsx with window.location.href calls to prevent React render error and content jump issue ()
Refactor: Check for presence of lng and translations static props before using useSSR

Changed

Refactored code to use TS' type-only imports feature ()
Refactor: i18next and react-i18next are now integrated for i18n solution instead of rosetta ()
Refactor: Default

v0.3.2 (2020-08-22)

Added

Added removeDeprecatedGapUtilities flag to Tailwind config file to opt-in to Tailwind's upcoming breaking change ()

Changed

Refactored custom TS type SupportedLocale to SupportedLanguage ()
Bumped NEXT_PUBLIC_APP_VERSION env var to 0.3.2 ()

v0.3.1 (2020-08-21)

A simple patch release to include the changes to the README and changelog that should have landed in the 0.3.0 release but didn't.

v0.3.0 (2020-08-21)

Added

file ready to be customized to enable the following core features: ()
- Customizable Base Path
- Rewrites, Redirects, and Headers

Changed

Updated the Branch Organization section of the contributing guide ()
Updated Features section of the README to include next.config.js file addition ()
Bumped NEXT_PUBLIC_APP_VERSION

v0.2.1 (2020-08-18)

Fixed

Fixed index page component's responsive design ()
Index page now correctly queries and shows latest release version ()

Changed

Removed version number from Docs badge in README ()
Added Code of Conduct ()
Added CONTRIBUTING file ()

v0.2.0 (2020-08-16)

Added

Converted starter template to TypeScript ()
Installed @meronex/icons package to allow SVG icons to be easily added.
Installed and configure Tailwind CSS framework.

Changed

Added documentation section and badge to README ()
Added mention of Tailwind CSS and Sass feature additions to the README ()
Replaced default Next.js README with project-specific README ()

v0.1.0 (2020-08-14)

First release to match default web app created by create-next-app with the following differences:

Development packages , and added and configured to enforce local linting of commit messages that follow the .
Commands added to the package.json scripts property to bump package version, and commit and tag releases.

Changelog

v0.6.2 (2020-09-11)

Changed

README: Re-ordered Getting Started options ()

v0.6.1 (2020-09-11)

Changed

Uninstalled github-buttons package ()
Updated i18next-http-backend and i18next-http-middleware dependencies ()

v0.6.0 (2020-09-11)

Added

PWA support via next-pwa ()

Changed

Revamped index page layout ()
Updated README, changelog, Code of Conduct and contributing guide () () ()
Updated tests that were broken by new index page layout ()

v0.5.0 (2020-09-06)

Added

Jest and React Testing Library ()
Unit tests for the homepage (including tests for the header and footer components) ()
file to simply site-wide configuration of your Next.js project ()

Changed

Refactor: Moved i18n and seo config files to config/ folder ()
README: Updated Features section ()

v0.4.0 (2020-09-03)

Added

Integrated Next SEO plugin library ()

Fixed

Refactor: Replaced router.push calls in src/lib/utils.ts and src/pages/index.tsx with window.location.href calls to prevent React render error and content jump issue ()
Refactor: Check for presence of lng and translations static props before using useSSR

Changed

Refactored code to use TS' type-only imports feature ()
Refactor: i18next and react-i18next are now integrated for i18n solution instead of rosetta ()
Refactor: Default

v0.3.2 (2020-08-22)

Added

Added removeDeprecatedGapUtilities flag to Tailwind config file to opt-in to Tailwind's upcoming breaking change ()

Changed

Refactored custom TS type SupportedLocale to SupportedLanguage ()
Bumped NEXT_PUBLIC_APP_VERSION env var to 0.3.2 ()

v0.3.1 (2020-08-21)

A simple patch release to include the changes to the README and changelog that should have landed in the 0.3.0 release but didn't.

v0.3.0 (2020-08-21)

Added

file ready to be customized to enable the following core features: ()
- Customizable Base Path
- Rewrites, Redirects, and Headers

Changed

Updated the Branch Organization section of the contributing guide ()
Updated Features section of the README to include next.config.js file addition ()
Bumped NEXT_PUBLIC_APP_VERSION

v0.2.1 (2020-08-18)

Fixed

Fixed index page component's responsive design ()
Index page now correctly queries and shows latest release version ()

Changed

Removed version number from Docs badge in README ()
Added Code of Conduct ()
Added CONTRIBUTING file ()

v0.2.0 (2020-08-16)

Added

Converted starter template to TypeScript ()
Installed @meronex/icons package to allow SVG icons to be easily added.
Installed and configure Tailwind CSS framework.

Changed

Added documentation section and badge to README ()
Added mention of Tailwind CSS and Sass feature additions to the README ()
Replaced default Next.js README with project-specific README ()

v0.1.0 (2020-08-14)

First release to match default web app created by create-next-app with the following differences:

Development packages , and added and configured to enforce local linting of commit messages that follow the .
Commands added to the package.json scripts property to bump package version, and commit and tag releases.

Folder Structure

After creation, your project should look like this:

├── .github
|   ├── contributing.md
├── __tests__
|   ├── Home-es.test.tsx
|   ├── Home-fr.test.tsx
|   ├── Home.test.tsx
├── config
|   ├── i18n
│   │   ├── config.ts
|   ├── jest
│   │   ├── cssTransform.js
│   │   ├── test-utils.tsx
|   ├── seo
│   │   ├── next-seo.config.ts
|   ├── app.config.ts
├── public
│   ├── locales
|   |   ├── en
|   |   |   ├── common.json
|   |   |   ├── footer.json
|   |   |   ├── header.json
|   |   |   ├── index.json
|   |   ├── es
|   |   |   ├── common.json
|   |   |   ├── footer.json
|   |   |   ├── header.json
|   |   |   ├── index.json
|   |   ├── fr
|   |   |   ├── common.json
|   |   |   ├── footer.json
|   |   |   ├── header.json
|   |   |   ├── index.json
│   ├── android-chrome-192x192.png
│   ├── android-chrome-512x512.png
│   ├── apple-touch-icon.png
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── favicon.ico
│   ├── site.webmanifest
│   ├── vercel.svg
├── src
|   ├── components
│   │   ├── layout
|   |   |   ├── Footer.tsx
|   |   |   ├── Header.tsx
|   |   |   ├── WebApp.tsx
│   │   ├── App.tsx
│   ├── i18n
│   │   ├── create-provider
|   |   |   ├── browser.tsx
|   |   |   ├── index.tsx
|   ├── lib
│   │   ├── types.ts
│   │   ├── utils.ts
│   ├── pages
│   │   ├── [lng]
|   |   |   ├── index.tsx
│   │   ├── api
|   |   |   ├── hello.ts
│   │   ├── 404.tsx
│   │   ├── _app.tsx
│   │   ├── _document.tsx
│   │   ├── _error.tsx
│   │   ├── index.tsx
├── styles
|   ├── Footer.module.scss
│   ├── Header.module.scss
|   ├── Home.module.scss
│   ├── index.css
├── .babelrc
├── .editorconfig
├── .env.development
├── .env.production
├── .gitignore
├── CODE_OF_CONDUCT.md
├── README.md
├── changelog.md
├── jest.config.js
├── license.md
├── next-env.d.ts
├── next.config.js
├── package.json
├── postcss.config.js
├── tailwind.config.js
├── tsconfig.json
└── yarn.lock

The purpose of each of these files and folders are as follows:

.github

This folder simply contains the project's Contributing Guide.

tests

This folder should contain all tests written. Currently unit tests are provided for each localized version of the template's index page.

config

Stores configuration files for most of the starter template's features:

i18n/config.ts - Used by our react-i18next integration. You should not modify this file to customize the configuration for your app, instead you should modify app.config.ts.
jest/cssTransform.js - Used by our Jest setup to transform .css files.
jest/test-utils.tsx - Loaded by each test file to set up the testing framework before each test.

public

Stores the following image and json assets:

locales - Contains sub-folders for each locale configured for the app, which in turn contain the locale translation files. This is an example of how to configure translation files to leverage i18next's Namespaces feature, more of which you can learn about .
favicon.ico, *.png - favicon and application icon files.

src

This is where the custom components, pages, Context API providers, typings and utility code for the project live.

Non-page components

Next.js WebApp Starter documentation

Introduction

hashtagWhat is Next.js WebApp Starter?

hashtagFeatures

hashtagProject Goals

hashtagWho created it?

hashtagHow can I contribute?

Getting Started

hashtagOption 1: Use create-next-app

hashtagOption 2: GitHub's Use this template feature

hashtagBefore you start coding

Folder Structure

hashtag.github

hashtag__tests__

hashtagconfig

hashtagpublic

hashtagsrc

hashtagstyles

Development

TypeScript Integration

Page Components

Custom `App`

Misc

Changelog

hashtagv0.6.2 (2020-09-11)

hashtagChanged

hashtagv0.6.1 (2020-09-11)

hashtagChanged

hashtagv0.6.0 (2020-09-11)

hashtagAdded

hashtagChanged

hashtagv0.5.0 (2020-09-06)

hashtagAdded

hashtagChanged

hashtagv0.4.0 (2020-09-03)

hashtagAdded

hashtagFixed

hashtagChanged

hashtagv0.3.2 (2020-08-22)

hashtagAdded

hashtagChanged

hashtagv0.3.1 (2020-08-21)

hashtagv0.3.0 (2020-08-21)

hashtagAdded

hashtagChanged

hashtagv0.2.1 (2020-08-18)

hashtagFixed

hashtagChanged

hashtagv0.2.0 (2020-08-16)

hashtagAdded

hashtagChanged

hashtagv0.1.0 (2020-08-14)

Introduction

hashtagWhat is Next.js WebApp Starter?

hashtagFeatures

hashtagProject Goals

hashtagWho created it?

hashtagHow can I contribute?

Custom `App`

Getting Started

hashtagOption 1: Use create-next-app

hashtagOption 2: GitHub's Use this template feature

hashtagBefore you start coding

TypeScript Integration

Changelog

hashtagv0.6.2 (2020-09-11)

hashtagChanged

hashtagv0.6.1 (2020-09-11)

hashtagChanged

hashtagv0.6.0 (2020-09-11)

hashtagAdded

hashtagChanged

hashtagv0.5.0 (2020-09-06)

hashtagAdded

hashtagChanged

hashtagv0.4.0 (2020-09-03)

hashtagAdded

hashtagFixed

hashtagChanged

hashtagv0.3.2 (2020-08-22)

What is Next.js WebApp Starter?

Features

Project Goals

Who created it?

How can I contribute?

Option 1: Use `create-next-app`

Option 2: GitHub's `Use this template` feature

Before you start coding

.github

tests

config

public

src

styles

v0.6.2 (2020-09-11)

Changed

v0.6.1 (2020-09-11)

Changed

v0.6.0 (2020-09-11)

Added

Changed

v0.5.0 (2020-09-06)

Added

Changed

v0.4.0 (2020-09-03)

Added

Fixed

Changed

v0.3.2 (2020-08-22)

Added

Changed

v0.3.1 (2020-08-21)

v0.3.0 (2020-08-21)

Added

Changed

v0.2.1 (2020-08-18)

Fixed

Changed

v0.2.0 (2020-08-16)

Added

Changed

v0.1.0 (2020-08-14)

What is Next.js WebApp Starter?

Features

Project Goals

Who created it?

How can I contribute?

Option 1: Use `create-next-app`

Option 2: GitHub's `Use this template` feature

Before you start coding

v0.6.2 (2020-09-11)

Changed

v0.6.1 (2020-09-11)

Changed

v0.6.0 (2020-09-11)

Added

Changed

v0.5.0 (2020-09-06)

Added

Changed

v0.4.0 (2020-09-03)

Added

Fixed

Changed

v0.3.2 (2020-08-22)

Added

Changed

v0.3.1 (2020-08-21)

v0.3.0 (2020-08-21)

Added

Changed

v0.2.1 (2020-08-18)

Fixed

Changed

v0.2.0 (2020-08-16)

Added

Changed

v0.1.0 (2020-08-14)

.github

tests