VSHN Website

This project contains the sources of the VSHN website.

Build Website

This section explains how to build and run the website.

Manually

1. Install Node.js version 16
   • This website will not build with versions other than 16.
   • It is recommended to use the Node Version Manager for this:

$ nvm install 16
$ nvm use 16
$ node --version
v16.20.2

2. Clone the repository:

$ git clone https://github.com/vshn/website.git
$ cd website

3. Install dependencies:

$ npm install

4. Build website; set the proper values to the environment variables and run the build:website task:

$ export WP_GRAPHQL_URL=...
$ export GATSBY_DEFAULT_SITE_URL=...
$ export GATSBY_CONCURRENT_DOWNLOAD=5
$ export WP_HTACCESS_USERNAME=...
$ export WP_HTACCESS_PASSWORD=...
$ npm run build:website

The build process can take up to 30 minutes. At the end of the process, the public dir under this project will contain the HTML website ready to use.

To view the website, it's not enough to open the public/index.html file on a browser; instead, you need a local webserver, for example using the PHP CLI for that:

$ cd public
$ php -S localhost:8080

Browse to http://localhost:8080 to see the website running.

Container

Set the proper environment variables and use the following command to build the container locally, as defined in the Dockerfile:

$ export WP_GRAPHQL_URL=...
$ export GATSBY_DEFAULT_SITE_URL=...
$ export GATSBY_CONCURRENT_DOWNLOAD=5
$ export WP_HTACCESS_USERNAME=...
$ export WP_HTACCESS_PASSWORD=...
$ podman build --secret id=WP_GRAPHQL_URL,env=WP_GRAPHQL_URL \
  --secret id=GATSBY_DEFAULT_SITE_URL,env=GATSBY_DEFAULT_SITE_URL \
  --secret id=GATSBY_CONCURRENT_DOWNLOAD,env=GATSBY_CONCURRENT_DOWNLOAD \
  --secret id=WP_HTACCESS_USERNAME,env=WP_HTACCESS_USERNAME \
  --secret id=WP_HTACCESS_PASSWORD,env=WP_HTACCESS_PASSWORD \
  --tag website .

NOTE: The container build process outputs the line /bin/sh: lscpu: not found every so often; this is a warning, and can be ignored.

You can run the resulting container using the following command:

$ podman run --rm --publish 8080:8080 website

Browse to http://localhost:8080 to see the website running. The final container is compatible with Red Hat OpenShift, using the ghcr.io/vshn/nginx as base image.

GitHub Actions

The build process can take up to 45 minutes. You can run the resulting container using the following command:

$ podman run --rm --publish 8080:8080 ghcr.io/vshn/website:master

Development

This section provides information about the development process.

Clean build products

$ npm run clean

Run the website

$ npm run start

Run Storybook

$ npm run storybook

Build the website

$ npm run build:website

Build Storybook

$ npm run build:storybook

Run the built website

$ npm run serve:website

Run built Storybook

$ npm run serve:storybook

Project Structure

├── src
│   ├── components
│   │  ├── pages — React components that are being used specifically on a certain page
│   │  └── shared — React components that are being used across the whole website
│   ├── hooks
│   ├── icons
│   ├── images — Images that are being quired using graphql. Read more about it here — gatsbyjs.org/docs/working-with-images. Also note, that folder structure should be equal to the structure of components folder
│   ├── layouts
│   ├── pages
│   ├── styles
│   ├── templates
│   ├── utils
│   └── html.js — HTML template for all generated pages. Read more about it here — gatsbyjs.org/docs/custom-html
├── static
│   └── fonts - Self-hosted fonts
├── gatsby-browser.js — This file is where Gatsby expects to find any usage of the Gatsby browser APIs (if any). These allow customization/extension of default Gatsby settings affecting the browser. Read more about it here — gatsbyjs.org/docs/browser-apis
├── gatsby-config.js — This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. Read more about it here — gatsbyjs.org/docs/gatsby-config
├── gatsby-node.js — This file is where Gatsby expects to find any usage of the Gatsby Node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process. Read more about it here — gatsbyjs.org/docs/node-apis
└── gatsby-ssr.js — This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs (if any). These allow customization of default Gatsby settings affecting server-side rendering. Read more about it here — gatsbyjs.org/docs/ssr-apis

Component Folder Structure

Each component includes

1. Main JSX File
2. SASS File
3. Index File

Each component optionally may include

1. Folder with images
2. Another component that follows all listed above rules.

Example structure

component
├── nested-component
│  ├── images
│  │  ├── image.svg
│  │  └── icon.inline.svg
│  ├── nested-component.jsx
│  ├── nested-component.module.scss
│  └── index.js
├── images
│  ├── image.svg
│  └── icon.inline.svg
├── component.jsx
├── component.module.scss
└── index.js

VS Code

Following extensions required to simplify the process of keeping the same code style across the project:

• ESLint
• Stylelint
• Markdownlint

After installation add these lines to your VS Code settings.json:

"editor.codeActionsOnSave": {
  "source.fixAll": true
},
"css.validate": false,
"less.validate": false,
"scss.validate": false

You can navigate to settings.json by using Command Pallete (CMD+Shift+P) and then type "Open settings.json".

Also, make sure that these extensions are installed too:

• CSS Modules
• GraphQL
• Code Spell Checker

Storybook

Storybook is a tool for previewing and building components in an isolated environment. Storybook also allows us to change props using knobs showing the developer what happens when a specific value is used. We should use this for both a development environment and a documentation tool.

Style Variables

All style variables that being used across the whole website are stored in src/styles/variables.scss.