This app is a Next.js site deploying on Vercel.

• jambonz.vercel.app

• npm i
  • Installs packages and setup husky
• npm run dev
  • Serves local dev at localhost:3000
• npm run lint
  • Runs Next.js linting
• npm run build && npm run start
  • Create an optimized Next.js production build and serve it locally
• npm run build && npm run export
  • Create a static production export for any static deploy target

Head on over to the jambonz-ui repo for full documentation. Also check out the jambonz-ui docs as a more in-depth resource.

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 src/styles directory and loaded globally in pages/_app.js. JS components are in the src/components directory. The jambonz-ui component library consists of reusable design element components.

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.

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 _text-layout page(s) wherein we've chosen to have the p element implement the ms() mixin and likewise the li element(s) implementing the ms() mixin as well.

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.

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.

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 npm run dev in one shell and then npm run test in another shell. Optionally, you can npm run build && npm run start to create an optimized production server locally and in another shell run npm run test. The GitHub workflow for this repository runs the Cypress tests by building and then starting Next.js in the background like npm run build && (npm run start&) > /dev/null and then npm run 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 npm run 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