# Welcome

> **Version:** 1.4.x **License:** Commercial / GPL‑compatible **Requires:** WordPress 6.4+, PHP 8.0+

PorterWP is a *developer‑first* toolkit that turns any **WordPress block theme** into a fully‑fledged, schema‑driven application. It ships as a plugin and expects a companion **`/porter`** folder inside your child theme where all configuration lives.

* Zero‑boilerplate **Custom Post Types** & **Taxonomies** via JSON.
* **ACF Blocks**, **block styles**, **patterns** & **variations** without touching PHP.
* Automatic include of theme PHP helpers from **`/porter/inc`**.
* *Production‑only* object‑cache layer with a one‑click purge.
* A premium **Filters** block that adds faceted search to any Query Loop.

***

## Quick Start 🚀

1. **Buy & download PorterWP Premium** Get your license at <https://porterwp.com/> and grab the ZIP plus your Freemius key.
2. **Install the plugin** Upload via *Plugins › Add New* or run:

   ```bash
   wp plugin install ~/Downloads/porterwp-premium.zip --activate
   ```
3. **Activate your licence** A Freemius modal will prompt for the key; you can revisit it under *Plugins › PorterWP Premium › Manage License*.
4. **Install the latest skeleton theme** Download or clone the starter from <https://github.com/whoisandywhite/porterwp-public/tree/main/resources/theme-skeleton> **(it is a complete WordPress theme)** and drop the whole folder into `wp-content/themes/`.
   1. Rename the folder if you like (`my‑theme`, `client‑site`, …).
   2. Open **`style.css`** inside the theme and change the theme header (`Theme Name`, `Author URI`, etc.).
   3. Open **`package.json`** and update the `name` + `description` fields so NPM uses your project slug.
5. **Compile assets (optional, recommended)**

   ```bash
   npm install        # once
   npx gulp build     # production build
   npx gulp watch     # dev: SCSS → CSS, JS minify, etc.
   ```

### Recommended `wp-config.php` additions

```php
// Tell PorterWP when to cache
// Options: production, staging, development, local
if ( ! defined( 'WP_ENVIRONMENT_TYPE' ) ) {
    define( 'WP_ENVIRONMENT_TYPE', 'development' );
}
```

PorterWP only caches in `production`. Keeping other environments set to `development` or `local` means you never have to hit **Clear Cache** while theming.

> **Next →** [Directory Structure](https://whoisandywhite.gitbook.io/porterwp/documentation/directory-structure)

## Configuration Files

The JSON files inside `porter/config/` let you shape every aspect of the theme. See the [Configuration Files Index](https://whoisandywhite.gitbook.io/porterwp/documentation/configuration-files) for a full breakdown.

## Build Pipeline

PorterWP ships with a **Gulp 5 / ES modules** tool‑chain for compiling Sass, minifying JS, and generating block assets.

| File             | Purpose                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **gulpfile.js**  | Task definitions: compile SCSS, autoprefix, uglify CSS, minify JS, auto‑generate block style stubs, and create post‑type icons. |
| **package.json** | NPM dependencies and scripts for the build pipeline (no theme‑specific names—this is a prototype starter).                      |

```bash
# install dependencies
npm install

# one‑off production build
npm run gulp build   # or: npx gulp build

# watch files during development
npm run gulp watch   # or: npx gulp watch
```