Getting started with B P Collins

How to get B P Collins (www.bpcollins.co.uk) running locally and make your first safe change.

What this repository is

Only the theme and site-root files. No WordPress core, no plugins, no database, no uploads. The tracked content is:

• wp-content/themes/bpcollins/ — the whole theme (a fork of the StrategiQ base theme; style.css still says “Theme Name: StrategiQ”)
• site-root files: favicons, robots.txt, site.webmanifest, browserconfig.xml, wp-config-sample-base-theme.php
• bitbucket-pipelines.yml, CHANGELOG.md, README.md

Everything else — core, plugins, media, content — comes from a copy of the live site.

Accounts and access you need

Thing	Why	How
Bitbucket access to StrategiQ/www.bpcollins.co.uk	the repo; also holds the deploy pipelines and their variables	ask the account lead
WP Engine access	production/staging/dev environments, and a copy of the site to pull down	ask the account lead
Google Workspace account on the firm’s domain	wp-admin login is Google SSO (Google Apps Login Premium)	the firm’s IT, via the account lead
ACF PRO licence	ACF PRO is bundled as a zip in the repo, but activation needs the licence	StrategiQ shared credentials store
Mapbox	only needed if you change map styling; the public token is already in the theme JS	—

Never put credentials in this wiki or in the repository.

Local setup

1. Install Local (by Flywheel). The README specifies it and WP Engine’s copy tooling targets it.
2. Pull the site down. Easiest path is WP Engine → the environment → Copy site to Local (or export and import a backup). That gives you core, plugins, database and uploads.
3. Replace the theme with a clone of this repository so wp-content/themes/bpcollins is your working copy. Clone the repo somewhere and symlink or copy the theme directory into the Local site.
4. Check wp-config.php. wp-config-sample-base-theme.php shows the shape expected, including the lazy-load constants:

   define('LAZY_LOAD', true);
   define('LAZY_LOW_QUALITY', false);
   define('LAZY_PLACEHOLDER', true);

   Generate your own salts from https://api.wordpress.org/secret-key/1.1/salt/ — do not reuse the ones in the sample file.
5. Confirm the required plugins are active. TGMPA force-activates Yoast SEO, ACF PRO, Contact Form 7, Google Apps Login Premium, Redirection, Fly Dynamic Image Resizer, CookieHub and WP Rocket. Fly Dynamic Image Resizer is not optional — without it every image on the site renders empty, because get_responsive_image() delegates all resizing to it.
6. Set your dev URL in wp-content/themes/bpcollins/gulpfile.js:

   const urlToPreview = 'https://bpcollins.build/';

   Change it to your Local site URL. Don’t commit that change.

Build toolchain — read this before npm install

The toolchain is old: gulp 4, gulp-sass 4, node-sass 4.

npm install fails on modern Node. Verified on Node 22.22.2 (July 2026): node-sass@4 has no prebuilt binary, falls back to node-gyp, and dies with Can't find Python executable "python".

Use nvm and an older Node (Node 14 is the last release node-sass@4 supports):

nvm install 14
nvm use 14
cd wp-content/themes/bpcollins
npm install
npx gulp watch

gulp watch compiles SCSS and JS into assets/ and starts BrowserSync proxying urlToPreview. One-off builds: npx gulp compile (or gulp sass / gulp js).

The single most important thing to know about this repo: CI does not build anything, and assets/ is committed. If you change SCSS or JS and don’t run gulp, your deploy will succeed and change nothing. Always commit built assets alongside sources.

Where things are

wp-content/themes/bpcollins/
  functions.php        theme bootstrap, the two AJAX handlers, search relevance
  inc/                 feature modules (cpt, acf, cf7, seo, enqueue, security…)
  inc/classes/         BP* accessor classes + BlockMeta
  blocks/<slug>/       one directory per ACF block: .php .scss .js
  partials/            small reusable renderers, called via partial()
  acf-json/            ACF field groups (committed — field groups are code here)
  resources/scss|js/   sources for global CSS/JS
  assets/              BUILT output, committed
  single-*.php etc.    page templates, several of which hardcode a block stack

Read the architecture page next — it maps the features onto these directories.

Your first task

Something contained, in one block, that exercises the whole loop:

1. Pick a simple block (e.g. blocks/quote-block/).
2. Change something visible in its SCSS.
3. Run npx gulp watch and confirm the change appears in the browser via BrowserSync.
4. Confirm assets/css/quote-block/block-quote-block.css changed.
5. Commit both the SCSS and the built CSS.
6. Push to development and watch the Bitbucket pipeline deploy it.

That covers the build, the committed-assets rule and the deploy path in one go.

Conventions worth knowing on day one

• Blocks are directories. Registration is automatic from the directory name (inc/register-blocks.php). Renaming a block directory breaks every existing use of it in content.
• Two ways block assets load. Editor-placed blocks get CSS/JS from ACF’s enqueue_assets; blocks required by a page template do not, and must be added to that template’s hand-written enqueue array at the top of the file.
• BlockMeta is the field accessor. new BlockMeta then block_classes(), render_heading(), etc. Follow an existing block rather than calling get_field() directly.
• ACF field groups are committed in acf-json/ — commit them with your template change.
• There are no tests. No test runner, no CI test step. Verification is manual, in a browser, on staging.
• service posts and the services taxonomy on team are different things, and they are matched by slug or title. This trips up everyone once.
• Branches: development and staging auto-deploy on push; master deploys to production only via a manual pipeline.

When something breaks

Search this wiki first — the feature pages carry an “Invariants and gotchas” section that documents the traps found during the audit, including several live bugs. Query Monitor is installed and force-activated; use it for query and hook inspection.