• Next Web
  • Project structure
  • Stack
    • Linting
    • Tests
  • JotForms Integration
  • Setting up Ocelot for Storyblok

Next Web

Website front-end for www.nice.org.uk using NextJS

Project structure

The repository is set up as a monorepo. That is, there are various sub folders providing different parts of the project e.g. the web app and functional tests:

Folder	Purpose
web	NextJS web app
aws	AWS ECS hosting for the NextJS web app
api	Ocelot Api Cache

Stack

The common components of the stack are:

• VS Code IDE
  • With recommended extensions (VS Code will prompt you to install these automatically)
• TypeScript for static type checking
• Prettier for code formatting
• ESLint for JavaScript/TypeScript linting
• stylelint for SCSS linting
• Jest for JS unit testing
  • With React Testing Library

There are also more specific stacks detailed in the readme for each sub folder.

Linting

We use Prettier for code formatting, ESLint for JavaScript/TypeScript linting and stylelint for SCSS linting. All 3 are installed as dev dependencies and configured at the root level of this monorepo.

VSCode is also configured with the necessary extensions (via extensions.json) and settings (via settings.json) to do in-IDE linting and formatting. There's no further setup needed beyond installing the recommended extensions when you open the project. Just save source files and they'll be reformatted automatically.

Using VSCode should work for in-IDE linting but if it doesn't you can run the lint commands manually. Run npm run lint in the root to run Prettier, ESLint, stylelint and TS type checking against all source files. This includes source files for the NextJS web app, Jest tests and WDIO functional tests.

If you prefer using an IDE to command line, open the VSCode command palette (Ctrl + Shift + P) and choose Tasks: Run Task then Lint all the things.

Alternatively, run individual commands like npm run prettier, npm run lint:ts, npm run lint:scss or npm run ts:check for more granular control, although you shouldn't normally need to do this - IDE support and the single npm run lint command are usually enough.

Tests

We use Jest for JS unit testing with React Testing Library for testing React components.

vscode-jest is added as recommended extension (via extensions.json). This gives you the ability in-IDE to run and debug tests.

Use the command line instead if you need more granular control:

1. Run npm test to run the Jest tests (note: this doesn't run the WDIO functional tests)
   1. Or, run npm run test:watch to run the tests and watch for changes to files, to re-run the tests
   2. Or, run npm run test:coverage to run the tests and output a coverage folder with an lcov report.

Running tests in watch mode via npm run test:watch is most useful when developing locally.

JotForms Integration

We use an enterprise edition of JotForms, https://nice.jotform.com/myforms/ to host forms on the NICE Website through Storyblok.

For further information, please see docs/jotforms-integration.md.

Setting up Ocelot for Storyblok

Ocelot has been added as an alternative to Storybloks own inbuilt caching. To set up Ocelot for Storyblok locally the following steps need to be taken:

1. Ensure Redis is installed and running. Check that the redis endpoint URL is correct in the Ocelot section of appsettings.Development.json or appsettings.Production.json
2. There are two endpoints for clearing the Ocelot Cache, for which postman is used to access, these can be obtained from a developer or tester.
3. Amend the appsettings.Development.json or appsettings.Production.json so that the Ocelot.ClientSecret matches the client_secret in the Get Token postman request.
4. In the ocelot.development.json and/or ocelot.production.js in GlobalConfiguration add a BaseUrl key and the value is the local ocelot endpoint

"GlobalConfiguration": {
   "BaseUrl": "http://localhost:45127"
}

5. Open next-web/api/NICE.NextWeb.API.sln in Visual Studio and Run. You should be presented with a web page that says 'Not found'.
6. Ensure that in the Storyblok's .env file STORYBLOK_OCELOT_ENDPOINT correctly matches your local Ocelot endpoint URL and has a suffix of /storyblok. i.e. STORYBLOK_OCELOT_ENDPOINT=http://localhost:45127/storyblok
7. Run Storyblok, it should now use Ocelot for it's caching.

TRAC Integration

We have integrated Trac job boards with Nextweb using Storyblok. The integration allows the web content team to embed and render Trac jobs directly on the website.

Trac Component in Storyblok

A Trac Embed component is available in the Storyblok space. This component is used to render a specific Trac job board on a page.

Component Fields

Job Board ID

1. Required field.
2. This value populates the data-JobsBoardID attribute in the Trac embed script within the Nextweb TracEmbed component. Example: 10000 can be used initially to test the integration with sample vacancies.

Environment Variables Setup

Version

1. This is the current version of the JavaScript file referenced in the script URL. At the moment, it is v18.
2. If the version changes in the future, you must update the value in local.yml, TeamCity, and Octopus.

Integrity Key

1. The integrity key ensures the security and integrity of the Trac JavaScript file.
2. This value remains the same across all Trac embed scripts that reference the same version of the Trac script.
3. Whenever the Trac script version is updated, the integrity key must also be updated in local.yml, TeamCity, and Octopus.

Update your local.yml

Add the following configuration to your local.yml to ensure the Trac jobs page renders correctly:

public:
# ... more config here
trac:
  version: v18
  integrityKey: <VALUE> Replace it with correct value
# ... more config here

Script

We currently use the following script to render Trac job boards:

<script src="https://feeds.trac.jobs/js/v18/EmbeddedJobsBoard.js" integrity="<INTEGRITY_KEY>"></script>

Notes:

• If the integrity key changes, the version in the script URL may need to be updated.
• The data-JobsBoardID attribute is dynamically populated from the Storyblok Trac component.