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 intosite
) - Run
nvm use
followed byyarn
- 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 🚫 |
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 🚫 |
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. |
config.js
properties:
Root 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.
sanity.json
file
The Use the file cms/sanity-config.js
instead of sanity.json, but fill it out the same way. The only differences are:
- You can use any JavaScript you want, including environment variables and
require
statements - Leave out the
root
,api
, andproject
sections; these are dynamically added in and determined by the rootconfig.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, runsanity 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/ |