packages
has the example sites and theme itself:
defaults
is a completely empty Gatsby site which imports the theme and builds successfully, but does nothing else. It shows the Gatsby 404 page when you load the site. (This is intentional.)example-site
is a site which uses the components and queries from the theme, and should grow to reflect a minimum working site.gatsby-theme-project-portal
is the theme and incorporates all the shared components, layouts, templates, reused queries, and styling. It should be imported into the site as a theme
.project-portal-content-decap
is a plugin for
the theme which provides configuration for the Decap-CMS and loads data
from the JSON files it produces.storybook
is a component workbench based on
Storybook which displays the components and layout elements..prettierrc
is a configuration file for the prettier
JavaScript formatter.package.json
is the config file for the yarn
workspaces we use when developing the theme.test-packaging.sh
contains zsh
functions used for testing the packaging, publishing, and building of the sites without using yarn
workspaces (which was the main problem with the first implementation of the theme).yarn.lock
lists all the current package version used when setting up the workspaces.Brewfile
can be used by the macOS homebrew package manager to install project dependencies. For more info, run brew bundle --help
or visit https://brew.sh.node_modules
When you run yarn install
, the packages from ./.yarn/cache
are unpacked here.artifacts
is not checked in to the repository, but is where the yarn pack
command in the test scripts outputs the .tgz
file containing the theme.Important:
yarn
, not npm
.zsh
, not bash
You can install the dependencies (including node 18
and yarn berry
) by running:
brew bundle
Install the node
-dependencies and the workspaces:
yarn install
Run the example site in develop mode:
yarn workspace example-site develop
If you want to run the Decap CMS backend, then you need to start the Decap server in a separate terminal window.
In the packages/example-site
directory run:
npx decap-server
In the packages/example-site/static/config.yml
file, change the local_backend
parameter to:
local_backend: true
Then load the https://localhost:8000/admin/
to view the Decap CMS UI.
Run the Storybook in develop mode:
yarn workspace storybook develop
Updated components in
๐gatsby-theme-project-portal
will be shown in the
Storybook.
The release process is automated using GitHub Actions.
GitHub actions will run to create and publish NPM packages. Check in GitHub actions whether the process runs without errors and fix any errors which occur.
Test installing and building the theme using the test-packaging scripts, where you load the theme and other plugins from the registry instead of the local directory:
source test-packaging.sh
package-and-install -t "packages/example-site/" -w @thepolicylab-projectportals/gatsby-theme-project-portal,@thepolicylab-projectportals/project-portal-content-decap
This script simulates the package release and build process that the sites undergo during deployment via Netlify. This script is helpful when debugging strange errors in the build process, i.e. when errors only occur during deployment.
To set up the prettier code formatter, first install the dependencies (yarn install
) and then ensure that prettier
is activated in the dialog box: WebStorm > Preferences > Languages and Frameworks > JavaScript > Prettier.
The settings should be:
yarn:package.json:prettier
(only selectable if you have previously run yarn install
)