Gatsby-theme-esca-boilerplate NPM

website-boilerplate

Template repository for creating new websites. New for 2020.

To start a new website using this boilerplate, see Cloning into a New Website.

Jump to section:

Getting Started
Project Structure
Structure of Gatsby Site
CMS Structure/Configuration
Local Development
Cloning into a New Website

test change

Getting Started

Clone this repository and cd into the top level folder (i.e. not into site)
Run nvm use followed by yarn
Make sure you are logged into Netlify CLI and that your user has access to the boilerplate site (or whichever site you're working on that was cloned from the boilerplate) on Netlify
Run yarn env to copy initial environment variables from Netlify

You should now be able to use yarn dev, yarn build, etc. See Local Development or Cloning into a New Website below for more.

Project Structure

The project uses Yarn Workspaces to maintain a clean separation of code, dependencies, & scripts between the site & CMS. The various build/dev scripts are composed in the root package.json using npm-run-all.

Top-level workspace folders:

Folder	Description
`site`	The Gatsby site (see Structure of Gatsby Site below)
`cms`	The Sanity project; includes schemas, studio config & custom CMS components (see CMS Structure/Configuration below)

Top-level non-workspace folders:

Folder	Description
`functions`	Write Netlify functions in this folder; root `package.json` dependencies can be used
`functions/dist`	Holds the production builds of Netlify functions; built via netlify-lambda as part of the build/dev scripts
`scripts`	Node scripts for performing DevOps & build-related actions; used by the various scripts in the root `package.json` (see Local Development below)

Configuration files:

File Name/Path	Description
`netlify.toml` :no_entry_sign:	Do not edit this file, as it is dynamically generated and ignored by Git.
`config.js`	The main config file for non-sensitive project information that is site-specific. Do not store tokens/api keys here. Only use the properties that are pre-filled in this boilerplate, and carefully consider adding any others. Environment variables should be used for most things. See the table below for properties in this file.
`cms/sanity-config.js`	Replaces sanity.json and should mirror what it would normally contain, with some exceptions (see CMS Structure/Configuration).
`cms/sanity.json` :no_entry_sign:	Do not edit this file, as it is dynamically generated and ignored by Git.
`site/gatsby-config.js`	A fairly typical Gatsby configuration. Note that `developMiddleware` is extracted into a separate function imported from `site/dev-middleware.js`. See Structure of Gatsby Site below.

Root `config.js` properties:

Property	Description
`siteId`	ID for the Netlify site; same as the site's subdomain on netlify.com
`sanityName`	Project name to be displayed in the site's CMS; same as `project.name` in sanity.json
`sanityProjectId`	ID of the Sanity project to be used for the site's CMS; same as `api.projectId` in sanity.json
`sanityDataset`	The Sanity dataset to be used from the project specified above; same as `api.dataset` in sanity.json

Environment variables used:

Variable	Description
`GATSBY_ESCA_API_SITE`	Site context for Escalade web services; same as `ESC-API-Context` header
`X_API_KEY`	API key for Escalade web services; same as `X-API-KEY` header
`X_API_KEY_TEST`
`SANITY_TOKEN`	Token to access Sanity API; should be a read/write token

Structure of Gatsby Site

The Gatsby site is meant to be as dynamic as possible, so the structure of the pages/content is determined by CMS data wherever it can be. Therefore, there are no Gatsby pages or templates except for site/src/main-template.js, which is used by the local Gatsby plugins cms-pages and cms-templates to dynamically create all pages based on what is defined in the CMS.

Widgets in the CMS correspond to files in site/src/widgets/. The names of files (or subfolders with index.js) in this folder should be identical to the names of the widget types defined in cms/schemas/widget-types/.

The default export of site/src/widgets/index.js is a component that takes Sanity block content data & renders the appropriate components using @sanity/block-content-to-react. To ensure that the JS bundle for each page only contains code for the widgets it actually uses, this component also uses @loadable/component alongside gatsby-plugin-loadable-components-ssr to dynamically import the widget components at build time.

CMS Structure/Configuration

The CMS for the most part follows a typical Sanity structure. Some things have been tweaked.

The `sanity.json` file

Use the file cms/sanity-config.js instead of sanity.json, but fill it out the same way. The only differences are: 1. You can use any JavaScript you want, including environment variables and require statements 2. Leave out the root, api, and project sections; these are dynamically added in and determined by the root config.js file (see Project Structure)

Again, The sanity.json file is dynamically generated and ignored by Git, so it should not be edited.

Widgets in schemas

The directory cms/schemas/widget-types/ contains all the block content schema types in our configuration. Every one of them should have a name property matching a filename in site/src/widgets/ (e.g. BannerWidget). We refer to these semantically as widgets in many places.

Local Development

Yarn scripts:

Command	Description
`yarn env`	Fetches environment variables from Netlify build settings & writes to local `.env` file for use with the dotenv package
`yarn dev`	Runs the site, CMS and Netlify functions locally
`yarn build`	Builds the site, CMS and Netlify functions
`yarn ls-link`	Lists all the current packages that have been symlinked to the boilerplate/site via `yarn link` or similar; shows 3 separate lists for the site, CMS and root workspaces

Notes on linking monorepo packages

It's recommended to keep the escalade and escalade-internal monorepos cloned in folders directly adjacent to (i.e. at the same level as) the boilerplate and websites.

If you are linking a package in one of these monorepos and the package uses React as a dependency, you must also run npm link ../escalade/node_modules/react or npm link ../escalade-internal/node_modules/react. Make sure to use npm link in this scenario, as yarn link does not work for some reason.

The yarn ls-link script in the table above can be used to check which packages have already been linked. This lists packages linked with both yarn link and npm link.

Cloning into a New Website

Create a new GitHub repository and choose this repository as the template
Create a new Sanity project on sanity.io
Create a read/write token for the new Sanity project (make sure to save it)
Set up a new Netlify site pointing to the new repo and using the environment variables mentioned in Project Structure above
Edit the site's Settings in the Netlify UI according to the table down below
Clone the new repo locally and follow the Getting Started instructions
Edit config.js and set the properties described in Project Structure above
Make any desired changes to the Sanity schema in cms/schemas
From the cms folder, run sanity graphql deploy
Push changes to GitHub and deploy on Netlify

Netlify Site Settings

Navigate to:	Set to:
Build & deploy -> Build command	`yarn build`
Build & deploy -> Publish directory	`site/public/`
Functions -> Settings -> Functions directory	`functions/dist/`