@ensono-stacks/next

The next plugin contains generators to augment existing NextJs projects. Adding eslint rules, testing config as well as installing and configuring NextAuth.js in your NextJs app.

Using a standard setup for your Next app ensures consistency and code quality across multiple applications quickly. NextAuth (alongside Redis) can also be quickly added to a project without costly configuration and setup.

Using the deployment generator you can setup your application with the necessary infrastructure config to host it in k8s.

Prerequisites

An existing Next application. Note the generator will fail if run in an empty workspace with no applications. To create a new Next application please run the NX Next generator with the following command including any relevant options. See @nx/next plugin docs

nx g @nx/next:app my-new-app

Ensure the stacks -> executedGenerators fields are present within nx.json for FE code generation.

Ensure the stacks -> config fields are present and populated within nx.json for deployment/infra generation.

An example of the expected structure can be seen here under @ensono-stacks/workspace:init prerequisites.

Setting up @ensono-stacks/next

Install the @ensono-stacks/next with the following command:

npm
yarn

npm install --save-dev @ensono-stacks/next@latest

yarn add --dev @ensono-stacks/next@latest

Executors and Generators

To see a list of the plugin capabilities run the following command:

nx list @ensono-stacks/next

View additional information about a plugin capability through the following command:

nx g @ensono-stacks/next:[generator-executor-name] --help

Generators

@ensono-stacks/next:init

Adds custom config and developer tools to an existing next application

The next init generator will add a custom ESlint config to an existing NextJs application, install eslint-plugin-testing-library to the project. as well as update project.json with a custom test config to allow coverage collection from jest.

Prerequisites

An existing Next application

Usage

nx g @ensono-stacks/next:init

Command line arguments

The following command line arguments are available:

Option	Description	Type	Accepted Values	Default
--project	Name of the existing next application	string	nameOfApplication	N/A

Generator Output

The following files will be updated.

UPDATE apps/baseline-next-app/project.json #Updated with custom test config to allow for coverage collection
UPDATE apps/baseline-next-app/.eslintrc.json #Ehanced with additional linting rules
UPDATE apps/baseline-next-app/tsconfig.json #Minor enhancements
UPDATE apps/baseline-next-app/tsconfig.spec.json #Updates for monorepo structure
UPDATE apps/baseline-next-app/specs/index.spec.tsx #Formatting changes

The generator will also add react-axe (version 4.7.3) into the app via the following:

...app.tsx
// @ts-ignore
if (typeof window !== 'undefined' && process.env.NODE_ENV !== 'production') {
    // eslint-disable-next-line global-require
    const axe = require('@axe-core/react'); // eslint-disable-line @typescript-eslint/no-var-requires
    // eslint-disable-next-line global-require
    const React = require('react'); // eslint-disable-line @typescript-eslint/no-var-requires
    // eslint-disable-next-line global-require
    const ReactDOM = require('react-dom'); // eslint-disable-line @typescript-eslint/no-var-requires
    // eslint-disable-next-line @typescript-eslint/no-floating-promises
    axe(React, ReactDOM, 1000);
}

...

react-axe has been added so your app can be tested for accessibility and results will show in the Chrome DevTools console.

@ensono-stacks/next:next-auth

Add Next Authentication to your next application

The next-auth generator will create a new library and configure NextAuth.js into an existing Next application. It will add the initial configuration, add the session provider, setup an API endpoint and add local environmental variables. It will also configure provider specific setup.

Prerequisites

An existing Next application

Usage

nx g @ensono-stacks/next:next-auth

Command line arguments

The following command line arguments are available:

Option	Description	Type	Accepted Values	Default
--name	The name of the library	string	string	N/A
--directory	The location of where the library should be installed	string	string	N/A
--project	The name of the project	nameOfApplication	string	N/A
--provider	The provider to be installed	string	none, microsoft-entra-id, auth0	none
--sessionStorage	The session storage to be used	string	cookie, redis	cookie
--guestSession	Enable guest sessioins	boolean	true/false	true
--importPath	The library name used to import it	string	string	N/A
--skipPackageJson	Do not add dependencies to `package.json`	boolean	true/false	false

Generator Output

Creates a new Library with the given name. Contains the configuration for Auth.js, including provider and adapter setup, config, and token rotation.

Generated files
├── auth
│   ├── src
│   │   ├── actions
│   │   │   ├── index.ts
│   │   │   ├── oauth.ts
│   │   │   ├── profile.ts
│   │   ├── adapter
│   │   │   ├── index.ts
│   │   │   ├── redis-adapter.ts
│   │   │   ├── redis-repository.ts
│   │   ├── callbacks
│   │   │   ├── index.ts
│   │   │   ├── jwt.ts
│   │   │   ├── session.ts
│   │   ├── providers
│   │   │   ├── auth0.ts
│   │   │   ├── guest.ts
│   │   │   ├── index.ts
│   │   ├── types
│   │   │   ├── index.d.ts
│   │   ├── utils
│   │   │   ├── guards.ts
│   │   │   ├── index.ts
│   │   ├── config.ts
│   │   ├── index.ts
│   ├── .eslintrc.json
│   ├── jest.config.ts
│   ├── project.json
│   ├── README.md
│   ├── tsconfig.json
│   ├── tsconfig.lib.json
└── └── tsconfig.spec.json

Creates a new Next API endpoint with the file name [...nextauth].ts. This contains the dynamic route handler for NextAuth.js which will also contain all of your global NextAuth.js configurations. If you have specified a provider when running the generator this will be added to the providers array

/apps/appName/src/app/api/auth/[...nextauth]/route.ts
import { handlers } from "@my-stacks-workspace/auth";

export const { GET, POST } = handlers;

Install the next-auth package and add to package.json, unless the --skipPackageJson option was used

/package.json
"dependencies": {
    ...otherDependencies
    "next-auth": "5.0.0-beta.19",
    "ioredis": "5.4.1", // if using --sessionStorage=redis
},

Create or append an .env.local file. Adding required next auth environmental variables. These will vary depending on the provider chosen.

/.env.local
NEXTAUTH_URL=http://localhost:4200
NEXTAUTH_SECRET=secretValue
AZURE_AD_CLIENT_ID=
AZURE_AD_CLIENT_SECRET=
AZURE_AD_TENANT_ID=

note

Be sure to update the environmental variables with the values provided by your provider

Wrap client components with a session provider to access session state.

/apps/appName/src/components/client-component.tsx
"use client";

import { useSession } from "next-auth/react";

export default function ClientComponent() {
  const { data } = useSession();

  if (!data || !data.user || data.user.role === "guest") {
    return null;
  }

  return <div>{data.user.name}</div>;
}

/apps/appName/src/app/page.tsx
import { SessionProvider } from "next-auth/react";

import { auth } from "@my-stacks-workspace/auth";

import ClientComponent from "../components/client-component";
import GuestSessionProvider from "../components/guest-session";

export default async function Index() {
  const session = await auth();
  return (
    <>
      <SessionProvider session={session}>
        <GuestSessionProvider />
        <ClientComponent />
      </SessionProvider>
    </>
  );
}

For further information please see the Getting Started Guide to Next Auth

@ensono-stacks/next:storybook

Add Storybook to your next application

The storybook generator will install and configure Storybook into an existing Next application. It will add storybook configuration, a custom component command and storybook extensions. The following extensions are:

        {
            "@storybook/addon-essentials": "7.4.5",
            "@storybook/addon-actions": "7.4.5",
            "@storybook/addon-links": "7.4.5",
            "@storybook/manager-api": "7.4.5",
            "@storybook/preview-api": "7.4.5",
            "@storybook/addon-a11y": "7.4.5",
            "@storybook/addon-jest": "7.4.5",
            "@storybook/theming": "7.4.5",
        },

Prerequisites

An existing Next application

Usage

nx g @ensono-stacks/next:storybook

Command line arguments

The following command line arguments are available:

Option	Description	Type	Accepted Values	Default
--project	The name of the project	nameOfApplication	string	N/A
--skipPackageJson	Do not add dependencies to `package.json`	boolean	true/false	false

Generator Output

The generator creates the following:

creates a new folder .storybook. This contains information for the storybook package.
- main.js file is created
- preview.js file is created
creates a new file tsconfig.storybook.json to store configuration for storybook

The generator updates the following:

updates the project.json file to add the custom-component command

The generator installs the follow dependencies unless the --skipPackageJson option was used:

/package.json
{
    "dependencies": {
        "@storybook/core-server": "7.4.5",
    },
    "devDependencies": {
        "@nx/storybook": "16.9.1",
        "@storybook/nextjs": "7.4.5",
        "@storybook/addon-essentials": "7.4.5",
        "@storybook/addon-actions": "7.4.5",
        "@storybook/addon-links": "7.4.5",
        "@storybook/manager-api": "7.4.5",
        "@storybook/preview-api": "7.4.5",
        "@storybook/addon-a11y": "7.4.5",
        "@storybook/addon-jest": "7.4.5",
        "@storybook/theming": "7.4.5",
        "eslint-plugin-storybook": "0.6.15",
    },
}

Custom command for app

After the Storybook generator has been installed you can now run the new command custom-component that will add the following:

creates a component under a specified name
creates a test for the new component
creates a story for the new component

note

my-app is an example of your app's name.

nx run my-app:custom-component --name=component-x --folderPath=components

The flags are the following:

name: name of the component
folderPath: path of the new component folder (based on the app as the root of the path)

Prerequisites​

Setting up @ensono-stacks/next​

Executors and Generators​

Generators​

@ensono-stacks/next:init​

Prerequisites​

Usage​

Command line arguments​

Generator Output​

@ensono-stacks/next:next-auth​

Prerequisites​

Usage​

Command line arguments​

Generator Output​

@ensono-stacks/next:storybook​

Prerequisites​

Usage​

Command line arguments​

Generator Output​

Custom command for app​

Prerequisites

Setting up @ensono-stacks/next

Executors and Generators

Generators

@ensono-stacks/next:init

Prerequisites

Usage

Command line arguments

Generator Output

@ensono-stacks/next:next-auth

Prerequisites

Usage

Command line arguments

Generator Output

@ensono-stacks/next:storybook

Prerequisites

Usage

Command line arguments

Generator Output

Custom command for app