Clone this repository and install yarn. Important for developers: Run a fresh yarn install and make sure Husky installs on your local machine Your terminal output will show that husky has been installed after yarn resolves packages, something like this:

Commands

yarn install
- Installs node packages
- Installs husky for git pre-commit hooks
- Husky will run yarn build before a git commit and stop the commit if lint or build fails
yarn dev
- Serves local dev at localhost:3000
yarn lint
- Runs ESLint validations on source JS
- Install the ESLint plugin for Visual Studio Code
yarn build && yarn start
- Create an optimized Next.js production build and serve it locally
yarn build && yarn export
- Create a static production export for any static deploy target

Testing

Note cypress test suite is still a work in progress

You can run e2e tests for the site using Cypress. Cypress specs rely on running the Next.js site on port 3000 as the baseUrl so the best way to test locally is to yarn dev in one shell and then yarn test in another shell. Optionally, you can yarn build && yarn start to create an optimized production server locally and in another shell run yarn test. The GitHub workflow for this repository runs the Cypress tests by building and then starting Next.js in the background like yarn build && (yarn start&) > /dev/null and then yarn test.

Cypress specs are located at cypress/integration/.... The source of truth static YAML data should always be used when authoring Cypress tests so we've implemented a script that generates JSON data fixtures for Cypress from the YAML data before tests are run. When running yarn test what happens is:

A pretest script runs and generates the JSON fixtures for Cypress
The Cypress tests are run in headless mode
A posttest script runs and performs cleanup on the Cypress fixtures

Packages

Packages being used prominently in this apps source code are:

Jambonz UI library

This app is being composed in the manor of module > component > element, wherein a page is a module which is made up of components that are comprised of elements. We are using Next.js SASS located in the styles directory and loaded globally in pages/_app.js. A generally simple BEM CSS module naming convention is being used prominently. JS components are in the components directory. The jambonz-ui component library consists of reusable design element components.

You can view examples of the Jambonz UI component elements on this page here.

Jambonz Styling

We are using the BEM style for our CSS/SASS system. Please review current implementations in src/styles and take the time to understand the BEM style in order to properly name and design your components styling.

Jambonz Typography

You should always use the reusable components from the jambonz-ui component library. These typographic components implement our type-scale for our design system. When styling pages in which we want to adjust or tweak the type-scale you should always use the mixins provided in the SASS. This ensures when we decide to break out of our standard type-scale implementation for any given element(s) we retain a harmonious nature to our type sizing as it retains its responsive nature provided by the mixins. A perfect example of how we have already done this is for the docs page(s) wherein we've chosen to have the h1 element implement the h2() mixin and likewise the h2 element to implement the h3() mixin. We even have the li element(s) implementing the ms() mixin.

Static page data

We are using static data with yamljs and Next.js static props. Data files are located in the data directory. There's a JS data utility in lib/data.js that provides a method for "fetching" the static data for use with a Next.js pages async getStaticProps SSR method.

Jambonz markdown data

The project is generating some dynamic layouts with markdown files using static file JS utilities alongside Next.js static paths/props system. We are leveraging their catch-all dynamic routes logic. Example located at pages/docs/[[...slug]].js. The markdown files are in the markdown directory organized by subfolders. The markdown navigation structure is controlled in the relevant page YAML data located in the data directory for each markdown subfolder. You can create markdown files at will but they will not render in the sidebar nav until they are also added to the nav structure in the relevant data file. For example, the markdown files for the developer docs are located at markdown/docs/... and the YAML data for this layout is located at data/docs.yml.

We are using remark, remark-html and remark-gfm as well as gray-matter for parsing the docs markdown files. Code syntax highlighting is done with prismjs and the associative babel config is in the .babelrc file. It's important to leave the preset in this file that merges our config with next/babel so Next.js works properly.