This is a repository to try out custom plugins, custom Gutenberg blocks, etc. Get wild, but not too wild.
The twentytwenty-child
directory is a child theme based off the WP Twentytwenty. Use this to test simple custimizations.
This site is hosted on Pantheon on the Basic plan (details). It's running on WordPress 5 on PHP 7.1. Redis cache is not available to sites on the Basic plan.
In order to more easily recreate the production environment locally, Lando is used for local development. We also use Pantheon’s CLI, Terminus, to sync files and databases.
-
Install git
- Windows installer
- macOS
- Check if already installed with
$ git --version
- If not already installed, you will be prompted to install it.
- Check if already installed with
-
Install Terminus, Pantheon’s CLI tool
-
Install Composer
- Windows instructions
- macOS
- Install Homebrew
- Run
$ brew install composer
-
Install NodeJS 8.x (Windows, macOS)
- Note: We recommend asdf for managing multiple versions of Node
-
- Note: Yarn is a faster alternative to
npm install
- Note: Yarn is a faster alternative to
Create a .env
file.
Update it so that it looks something like the following:
DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress
# Optional variables
DB_HOST=database
# DB_PREFIX=wp_
WP_ENV=development
WP_HOME=http://APP_NAME.lndo.site
WP_SITEURL=${WP_HOME}/wp
# Generate your keys here: https://roots.io/salts.html
AUTH_KEY='generateme'
SECURE_AUTH_KEY='generateme'
LOGGED_IN_KEY='generateme'
NONCE_KEY='generateme'
AUTH_SALT='generateme'
SECURE_AUTH_SALT='generateme'
LOGGED_IN_SALT='generateme'
NONCE_SALT='generateme'
#plugin keys
ACF_PRO_KEY=`pluginkey`
-
Clone this repo
$ git clone [email protected]:Threespot/threespot-wp-sandbox.git
-
Open
threespot-wp-sandbox
folder in the terminal and install Composer dependencies$ composer install
-
Start the local server
$ lando start
-
If everything was successful, you should see something like this:
Your app has started up correctly. Here are some vitals: NAME threespot-wp-sandbox LOCATION /Users/yourUserName/Sites/threespot-wp-sandbox SERVICES appserver_nginx, appserver, database, cache, edge, edge_ssl, index APPSERVER_NGINX URLS https://localhost:32774 http://localhost:32775 EDGE URLS http://localhost:32776 https://threespot-wp-sandbox.lndo.site/:8000 https://threespot-wp-sandbox.lndo.site/ EDGE_SSL URLS https://localhost:32777
-
-
Clone the database and files from Pantheon
$ lando pull
- Use the arrow keys to select “none” for the code, since we pulled the code from GitHub:
? Pull code from? live dev test ❯ none
- Select “live” for the database:
? Pull database from? ❯ live dev test none
- Select “live” for the files (NOTE: ALDF has ~4,000 images, so if this takes too long you can select “none” to skip this but you will not see any images locally)
? Pull files from? ❯ live dev test none
- Use the arrow keys to select “none” for the code, since we pulled the code from GitHub:
-
You should now be able to view the site at https://threespot-wp-sandbox.lndo.site/
-
You should be able to login to the admin at https://threespot-wp-sandbox.lndo.site/wp/wp-admin/
If the site fails to load, try the following:
-
Restart the server
$ lando restart
-
Rebuild the app
$ lando rebuild
-
Destroy and recreate the app
$ lando destroy && lando start
-
Check current version of Lando to see if there’s an update available
$ lando version
If you plan to make CSS or JS updates, you must run Webpack to recompile and inject the CSS and JS.
-
In a new terminal window, navigate to the
threespot-wp-sandbox
project folder again -
Navigate to the theme folder
$ cd /web/wp-content/themes/threespot-wp-sandbox
-
Install npm dependencies using Yarn
$ yarn install
-
Start Webpack
$ yarn start
- You should see the following:
[HTML Injector] Running... [Browsersync] Proxying: https://threespot-wp-sandbox.lndo.site [Browsersync] Access URLs: ----------------------------------- Local: https://localhost:3000 External: https://10.0.5.35:3000 ----------------------------------- UI: http://localhost:3001 UI External: http://localhost:3001 ----------------------------------- [Browsersync] Watching files...
- You should see the following:
-
You should now be able to view the site locally at https://localhost:3000
-
To stop the server, press Control + C
- If the server won’t start or gets caught in an endless loop, try stopping and restarting it.
- If the server starts but the site doesn’t appear at https://localhost:3000, check that
devUrl
inconfig.json
matches the URL generated by Lando (e.g. https://threespot-wp-sandbox.lndo.site)
To update WordPress or any free plugins to the latest version, run $ composer update
and push the updated composer.lock
file to GitHub. To update any paid plugins, you will need to manually update the files and commit.
To update the Node dependencies, run $ yarn upgrade-interactive
from the theme folder (threespot-wp-sandbox/web/wp-content/themes/threespot-wp-sandbox
) and select the packages to update. Once installed, push the updated yarn.lock
file to GitHub.
It is technically possible to install plugins via the WordPress admin with Pantheon (docs) but this isn’t recommended since it makes it difficult for multiple developers to stay in sync.
Every time code is pushed to GitHub, CircleCI will build and deploy the files to Pantheon’s dev environment. You can tell CircleCI not run by adding [skip ci]
to the commit message.
Once code has been deployed to the dev environment, you can switch to the “Test” tab and click the “Deploy Code from Development to Test Environment” button to deploy to http://test-threespot-wp-sandbox.pantheonsite.io.
After the updates have been tested, you can deploy to the live site by following the same process on the “Live” tab.
- Bedrock framework
- Places core WordPress code in a separate folder (required for Pantheon)
- Composer integration
- Environment variable support
- Supports autoloading regular and must-use plugins
- Sage theme framework (docs) with Soil plugin
- Supports Laravel’s Blade templating engine
- Supports controllers (docs) to keep views DRY
- Includes Webpack for processing front-end assets (config)
- Sass linting, compilation, browser prefixing, and minification
- JavaScript linting, transpilation (i.e. converting ES6 to ES5), bundling, and minification
- Image compression (config)
- Live reload with BrowserSync
- Community support for both frameworks can be found at https://discourse.roots.io
- Threespot’s CSS reset
- Threespot’s Sass library (docs)
- Most often used functions and mixins:
fs-rem
—Helper function converts pixels to remsfs-color
—Helper for retrieving a color from the$fs-colors
mapfs-min-width
/fs-max-width
—Media query helpers to convert fixed pixels to remsfs-media
—Media query helper that supports any condition, and multiple conditionsfs-scale
—Allows for smoothly scaling values from one viewport width to anotherfs-attention
—Helper mixin adds:hover
,:focus
, and:active
statesfs-svg
—Function to export URL-escaped inline SVG for use inbackground-image
(SVGs are stored in$fs-svg-icons
map)
- Most often used functions and mixins:
- SUIT CSS class naming convention, e.g.
.ComponentName-child--variation
-
Modernizr used for CSS grid and object-fit feature detection
-
External JS dependencies are listed in the
dependencies
section ofpackage.json
:View dependencies
- Custom JS modules can be found in the
/resources/assets/scripts
folder
- Custom JS modules can be found in the
The site JS is split into three files:
critical.js
—Contains code that needs to run before content is displayed in the browser to prevent a FOUC (e.g. check is JS is enabled, check if fonts have previously loaded)- NOTE: This code must be manually minified and copied to
critical-js.blade.php
(easier than setting up a custom build script since this code won’t change often)
- NOTE: This code must be manually minified and copied to
main.js
—Contains all other site JS, with the exception of image galleries; loaded at the bottom the<body>
tag