WP SURF Theme

• Requirements
• Installation
  • 1. Install composer packages
  • 2. Install npm packages
• Start work son!
• Staying up to date
• Running locally
• Glossary
• Troubleshooting

Requirements

You'll need to have the following items installed on your computer before continuing. NOTE: You only have to this once. If you already have all of this, please continue to 'Installation'.

• SourceTree or Git: Use the installer provided on the SourceTree or GIT website.
• PHP: Either use your OS' package manager, or download it from the php website
• Composer: Use the installer provided on the Composer website. (Install GLOBALLY)
• Node.js: Use the installer provided on the NodeJS website.

Installation

1. Install composer packages

Navigate to the theme folder (where composer.json is located) and install composer.

cd wp-content/themes/wp-surf-theme
composer install

2. Install npm packages

While still in the theme foler install the npm packages.

npm install

Start work son!

Now you can start working. While still in the theme folder run and watch npm like this:

npm run watch

When building for live run this:

npm run build

Compiled files will be placed in ./wp-surf-theme/assets/**/*. This why we keep our files structured. Keep in mind that our css files theme.css, admin.css, admin.editor.css will also be located in this structure rather than using the ./wp-surf-theme/style.css.

Staying up to date

Don't forget to update npm packages once in a while. While in the theme folder, run this to update:

npm update

Running locally

You can use Docker + Docker Compose to run the site locally.

First, you have to install all the composer and npm dependencies, for this you will need to install PHP, Node , Composer and Subversion.

composer install
cd wp-content/plugins
composer install
cd ../themes/wp-surf-theme
npm install
npm run build

Make sure you have Docker and Docker Compose.

Once all dependencies are installed and Docker has been set up you can run (in the project root):

docker-compose up

This will start a WordPress and a MySQL instance.

On MacBooks with the M1 chipset you might run into issues when trying to start a MySQL container. In that case you can try running:

docker pull --platform linux/x86_64 mysql
# Now docker-compose up should work
docker-compose up

The WordPress instance will be available at localhost:8080 and the MySQL instance will be available at localhost:13306. The first time you visit this website you'll have to click through the usual WordPress setup steps where you create an admin user.

Before you can start development you will have to enable the starter-theme and the already provided plugins in the admin interface.

Once that's done you'll have the following commands available for helping you during development:

./cowboy db:seed # Add test data to the database
./cowboy db:refresh # Remove all posts and postmeta from the database
./cowboy db:refresh --seed # Remove al posts and postmeta from the database and generate new test data

Glossary

• Composer: Dependency manager for PHP.
• Node.js: Lightweight and efficient real-time applications in JavaScript.
• Webpack: JavaScript bundler.

Troubleshooting

Keep your Node.js and npm updated. Ask colleagues for help.

WINDOWS

Remove the 'node_modules' folder, run:

mkdir empty_dir
robocopy empty_dir node_modules /s /mir
rmdir /S empty_dir
rmdir /S node_modules