Uses Gatsby to build static site.
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
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.)
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.
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
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)
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
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.
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
npm run build
before make stage
.
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.
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:
- On the
main
branch, rungit pull
followed bynpm ci
. - 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. - 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.
origin
points to a fork.
Gatsby Cloud uses set GitHub branches to build sites. Right now, we have:
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.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.
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.
Tests can be run using:
npm test # alias for npm run test
Unit tests are located in the tests/unit/
directory. To run only unit tests, use:
npm run test:unit
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
.
Snapshots may require updates when making changes to snooty components
npm test -- -u
We use ESLint and Prettier to help with linting and style.
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.
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.
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.