MongoDB Documentation Front-End

Uses Gatsby to build static site.

Installation

Snooty uses artifactory that will need authentication to install some private npm packages. Update your local zsh variables in $~/.zshrc (in Windows %USERPROFILE%/.zshrc) to include the following

export NPM_BASE_64_AUTH=<BASE_64_API_KEY>
export NPM_EMAIL=<your.email@gmail.com>

Then, to install the package dependencies:

npm install --legacy-peer-deps

.env file setup

You'll need to set some environment variables in two separate files at the root of this directory for separate production/development environments. These variables let Snooty know where to look for your AST zip files, within DOP team's database. (You can also use local AST files.)

.env.development

Snooty's develop stage uses the development environment. Your .env.development file should be as follows:

GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true

The GATSBY_SNOOTY_DEV variable is what allows Gatsby to know that it should use the snooty branch name as part of the file paths. When not set, the file paths will use the value of GATSBY_PARSER_BRANCH. See pathing here

It should be set to true when working on snooty locally.

.env.production

Snooty's build and serve stages use the production environment. Your .env.production file should be as follows:

GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true

Running locally

npm run develop

To build and serve the site, run the following commands: The serve command generates the site at a prefix ie. localhost:9000/<branch>/<docs-name>/<user>/<branch-name>/

$ npm run build
$ npm run serve

To debug server side:

node --nolazy node_modules/.bin/gatsby develop --inspect-brk

and connect a node debugger (ie. chrome developer tools)

Running with local manifest path

Alternative to working with remote AST files, you can have a local zip file to build the site. This removes the need for previously mentioned env variables required for remote lookup GATSBY_SITE GATSBY_PARSER_USER and GATSBY_PARSER_BRANCH. Local zip file is an output of the parser

.env.development and .env.production:

GATSBY_MANIFEST_PATH=/path/to/zipped/ast/file.zip
GATSBY_SNOOTY_DEV=true

Running with Gatsby Cloud preview

Snooty uses Gatsby Cloud to perform content staging builds for MongoDB documentation. These builds source their ASTs through the Snooty Data API and require additional environment variables for setup. To emulate a Gatsby Cloud preview build locally, include the following in your .env.development file:

GATSBY_CLOUD_SITE_USER=<YOUR GITHUB USERNAME>

Since building with the Gatsby Cloud preview source plugin expects build data to be present in our team's database, please use the Autobuilder to perform one or more builds prior to running the frontend. Otherwise, use a different GATSBY_CLOUD_SITE_USER.

When ready, run the following command:

npm run develop:preview

This command will run the gatsby-source-snooty-preview source plugin, where all AST data for the specified GATSBY_CLOUD_SITE_USER will be used to mimic a Gatsby Cloud site locally. All build data across every unique project + branch combination for that user will be built on the single site. To access the built content, go to http://localhost:8000/<PROJECT>/<BRANCH>/<PAGE_PATH>.

Note that this process assumes that the default public Snooty Data API endpoint is being used. If the staging instance of the API is desired, you will need to set the API_BASE env to the staging URL, include the expected client credentials as environment variables (found in Parameter Store), and then run the build on the office VPN. Please see the team's Gatsby Cloud template sites as examples.

Staging

Install libxml2 with brew install libxml2 on mac and apt-get install libxml2 on linux

Install mut and ensure that you have properly configured your Giza/AWS keys as defined here. Then, from root, run:

npm run build:clean:stage

⚠️ Note: This will promote the contents of your local public directory. Your instance in staging may break or be outdated if you haven't run npm run build before make stage.

Staging with Gatsby Cloud preview

If your changes specifically affect Gatsby Cloud preview builds, set up and use your own Gatsby Cloud site (denoted by GitHub username) in our team's organization. The feature branch can be assigned to the Gatsby Cloud site. Multiple feature branches in parallel may require the use of multiple Gatsby Cloud sites. See this wiki page for help with setup.

Releasing

We have configured an automatic release process using GitHub Actions that is triggered by npm-version. To release a version, you must have admin privileges in this repo. Then proceed as follows:

1. On the main branch, run git pull followed by npm ci.
2. Run npm version [major | minor | patch], using Semantic Versioning guidelines to correctly increment the version number. Keep the minor version consistent with snooty-parser versioning. GitHub Actions will create a new git tag and push it to GitHub.
3. Update the release draft found here using the automatically generated CHANGELOG.md and publish the release. Keep "pre-release" checked until version 1.0.0.

⚠️ This process cannot be completed if the releaser's origin points to a fork.

Gatsby Cloud

Gatsby Cloud uses set GitHub branches to build sites. Right now, we have:

1. gatsby-cloud-latest - Used by the Gatsby Cloud sites for the docs team. This branch should typically have the latest production release tag used by the Autobuilder.
2. gatsby-cloud-rc - Used by Gatsby Cloud sites designated for pre-production. This branch should be used for testing release candidates end-to-end with the Autobuilder in preprd.

When a new frontend release tag is made, use the commands below to update the desired Gatsby Cloud branch.

⚠️ Note that the following commands include a force push to make it easy to update and rollback the branch as needed.

git fetch origin --tags
git checkout tags/<tag>
git push -f origin HEAD:<gatsby-cloud-rc|gatsby-cloud-latest>

Once the branch is updated with a given tag, all Gatsby Cloud sites using that branch will be rebuilt. Ideally, gatsby-cloud-latest is only updated after the Autobuilder has completed its latest release, to ensure versions of the frontend and parser are compatible.

Testing

Tests can be run using:

npm test  # alias for npm run test

Unit tests

Unit tests are located in the tests/unit/ directory. To run only unit tests, use:

npm run test:unit

Running individual suites

Jest includes configurations for running individual test suites:

npm test -- my-test   # or
npm test -- path/to/my-test.js

For more information, see the Jest CLI Options documentation, or run npm test -- --help.

Updating test snapshots

Snapshots may require updates when making changes to snooty components

npm test -- -u

Lighthouse Scores

We use Lighthouse to keep track of our Core Web Vitals over time.

LHCI

Our dedicated DOP Lighthouse Server is hosted on Kanopy at https://docs-lighthouse-server.docs.prod.corp.mongodb.com/ The server code can be found here.

Every push to Snooty's main branch runs Lighthouse reports on the current docs and cloud-docs landing pages and uploads them to our Lighthouse Server for easy access and comparison.

Linting & Style

We use ESLint and Prettier to help with linting and style.

Lint

Our CI (via GitHub Actions) is configured to test for lint errors. To run this test locally and attempt to automatically fix errors:

npm run lint:fix

These errors must be fixed for the CI build to pass.

Style

To format code using Prettier, run the following command:

npm run format:fix

We have set up a precommit hook that will format staged files. Prettier also offers a variety of editor integrations to automatically format your code.

Component Factory Filter

The component factory filter process uses SWC to remove unused components from the ComponentFactory.js file. A custom plugin is used to perform this transformation, and it lives in the component-factory-transformer directory. This plugin is run when the npm run build command is executed.

To use the custom plugin, you'll first need to install Rust.

Once Rust is installed, you'll need to build the plugin. Change directory to component-factory-transformer, run cargo build && rustup target add wasm32-wasi if you haven't, and then run npm run prepublishOnly.

The USE_FILTER_BRANCH environment variable needs to be added in the .env.production file and set to true for this to work.

NOTE: This will modify the ComponentFactory.js file directly. To undo this, you can run git restore src/components/ComponentFactory.js to get the file back to its original state.

To perform a dry run i.e. the ComponentFactory.js file does not get updated, the FILTER_DRY_RUN property can be provided and set to true. This will log the resulting code that would have been written to the file only.

Useful Resources

React Gatsby Emotion mongodb/Realm LeafyGreen UI