Getting a Next.js application up and running is not a trivial exercise. This template solves a lot of initial problems and gets you to a well-scaffolded, responsive web application with some built-in navigation and support for all the goodies.

This template is highly opinionated with respect to toolchain. It is hard to get all of these bits to work together. It isn't hard to find a template that provides a basic platform. The challenge is to fill that template out into a machine that supports the development process in a robust matter.

It is hard to get all of those bits to work together. It is way easier to cut out the bits you don't need than figure out how to slot in the things you do. So that's what we have here.

Because this is a Next.js template, it works perfectly when deployed to Vercel. I've tried hard to make it host-agnostic, though, and I know for a fact that it works just as well deployed to AWS Amplify. It should work fine at any host that supports Next.js.

In order to work effectively with this template, you need to be familiar with the following technologies (click the links to do a deep dive):

Use VS Code as your code editor! This is non-negotiable, for reasons that will become obvious in step 2 below.

1. Clone this repository to your local machine.

2. VS Code will ask to install a bunch of recommended extensions. Accept all of them.

3. Install dependencies by running npm install.

4. Remove the .template extension from .env.local.template and .env.development.local.template. These files are blocked by .gitignore, so they are safe for environment secrets!

5. Start the development server by running npm run dev.

6. Visit the web application at http://localhost:3000.

This template includes release-it support that requires these final configurations:

1. Create a copy of .env.development.local.template and name it .env.development.local

2. Create a GitHub personal access token and add it as the value of GITHUB_TOKEN in .env.development.local.

You can now build your project and publish a release to GitHub and NPM with these commands:

npm run build
npm run release

When you to this, you will find that your sidebar menu and site footer contain a link to the current version's release notes. You can configure this by editing the component at components/page/SidebarItemsReleaseNotes.jsx.

lodash is the classic Swiss-army-knife library: you could always code around it, and it isn't always appropriate, but it's super nice to have it in your back pocket.

Trouble is, it's a HUGE library. You can cherry-pick from it, but that gets painful fast. So I've included & configured babel-plugin-lodash. Now you can just import the entire library in your code, like this:

import _ from 'lodash';

Babel will cherry-pick from lodash for you at build time!

If the following environment variable condition is true, the application will display a coming soon page:

process.env.NEXT_PUBLIC_COMING_SOON === '1' &&
  process.env.NEXT_PUBLIC_VERCEL_ENV !== 'preview';

If it is false, then the application will display.

In the development environment, both variables may be set explicitly in .env.development. In deployed environments, they are set explicitly in .env.production but may be overridden in your deployment pipeline.

If you are hosted at Vercel, the hosting environment will populate the NEXT_PUBLIC_VERCEL_ENV environment variable to reflect your deployment type. This value will be production on your production branch and preview on all other branches.

This template uses the Semantic UI React component set.

Your starting point is a nice reactive layout with a sticky sidebar that collapses down to a hamburger menu at mobile resolutions. There were some difficulties getting this to work properly with the installed version of Semantic UI; I've resolved these and commented those fixes in the code.

The Semantic toolkit is super flexible, so you can easily morph this into whatever layout works for you.

Semantic UI has a fantastic LESS-based theming system. It was a HUGE challenge getting this working properly within the Next.js context. Problem solved, though, so out of the box this template offers full Semantic UI theme support.

All aspects of the site theme can be controlled by modifying the contents of the semantic-ui directory.

Out of the box, this template leverages the default Semantic UI theme. Switch themes globally or at a component level by modifying the theme.config file. Override every conceivable aspect of the current theme, with full access to all related LESS variables, by editing the templates in the site directory. To examine existing themes and borrow their settings as overrides, see the contents of node_modules\semantic-ui-less\themes.

See here to learn more about Semantic UI themes.

[TODO]

[TODO]

[TODO]

[TODO]

[TODO]

User authentication is enabled using NextAuth.js against an Amazon Cognito User Pool.

For simplicity, we are assuming that the Cognito User Pool has its hosted UI configured. This supports a wide variety of federated login providers, including social logins like Google, Facebook, etc. See this template for an example of how to set this up.

NextAuth can secure front-end routes (i.e. pages) and back-end routes (i.e. API endpoints). You can also pass session credentials to other resources secured by the same authentication provider, for example an AWS API Gateway route.

This template demonstrates the following scenarios:

The home page at / is open to the public.

The page at /private is only visible to authenticated users. This is accomplished by adding the route pattern to the config variable in middleware.js, like this:

export const config = { matcher: ['/private'] };

If an unauthenticated user attempts to access this page, he will be redirected to a login page.

Note that the link to the Private page only appears in the sidebar when the user is authenticated. This is accomplished in SidebarItems.jsx. Note that router.push does not support shallow routing to protected pages!

• Connection to AWS API template
• API endpoints