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

1. Clone this repository and cd into the top level folder (i.e. not into site)
2. Run nvm use followed by yarn
3. 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
4. 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

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