# Theme Bundling

> Theme Bundling & Root Folders

- Skill: `comeonoliver/theme-bundling` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/theme-bundling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/theme-bundling/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/theme-bundling

---

# Theme Bundling & Root Folders

This skill ensures that any new root-level folders added to the WP Rig theme are properly included in the production bundle.

## Configuration & Export

Before modifying the theme structure or preparing a bundle, you **MUST** reference the `config/config.json`.

*   **Export Rules:** If you add a new root-level directory for assets or plugin overrides (e.g., `woocommerce/`), you **MUST** add it to `export.filesToCopy` to ensure it is included in the production bundle.

## Reasoning

WP Rig's build system uses a combination of specialized tasks (`phpTask`, `images`, `fonts`, `buildJS`, `buildCSS`) and a manual file-copying task (`prodPrep`).

- **Specialized Tasks**: These tasks automatically handle specific file types in specific locations (e.g., `.php` files anywhere in the theme, except for excluded directories like `node_modules` and `vendor`).
- **prodPrep Task**: This task manually copies files and folders specified in the `export.filesToCopy` property of the theme's configuration. It is used for files that are not handled by specialized tasks or for folders that need to be explicitly included in the bundle.

When you add a new root-level folder to the theme (especially for plugin template overrides like `woocommerce/` or `tribe-events/`), it is **mandatory** to add it to the `export.filesToCopy` array in `config/config.json`.

### Why this is necessary:

1. **Inclusion of Non-PHP Files**: While `phpTask` will automatically find and process `.php` files in your new folder, it will ignore other file types (e.g., `.css`, `.js`, `.json`, `.svg`, `.txt`). Adding the folder to `filesToCopy` ensures that *all* files within it are included in the bundle.
2. **Explicit Intent**: Adding the folder to the configuration explicitly signals that it is a required part of the theme's production bundle.
3. **Directory Structure Preservation**: The `prodPrep` task ensures that the directory structure of the specified folders is accurately preserved in the bundled theme.

## Decision Tree: Should I add this folder to `config.json`?

When a new root-level folder is added, ask the following:

1. **Is it a standard WP Rig core folder?** (e.g., `inc`, `assets`, `template-parts`, `languages`)
   - **No**: Proceed to the next question.
   - **Yes**: These are already handled by existing tasks. No action needed.

2. **Is it an excluded/development-only folder?** (e.g., `node_modules`, `vendor`, `tests`, `bin`, `scripts`, `artifacts`, `optional`, `wp-cli`, `childify_backup`)
   - **No**: Proceed to the next question.
   - **Yes**: Do not add to `config.json`. These should never be bundled.

3. **Is it a plugin template override folder?** (e.g., `woocommerce`, `tribe-events`, `buddypress`, `edd`)
   - **Yes**: **Add to `config.json`**. These must be included in the bundle for the theme to function correctly with those plugins.

4. **Does the folder contain non-PHP files that are required in production?**
   - **Yes**: **Add to `config.json`**.

## How to add a folder to `config.json`

If the folder is `woocommerce`, you should add it to the `export.filesToCopy` array in `config/config.json`.

### Example `config/config.json`:

```json
{
  "theme": {
    "enableBlocks": true
  },
  "export": {
    "filesToCopy": [
      "woocommerce/**/*"
    ]
  }
}
```

*Note: Use the glob pattern `folder-name/**/*` to ensure all files and subdirectories are included.*

## Verification

After adding a folder to `config.json`:

1. Run the bundle command: `npm run bundle`
2. Verify that the new folder and its contents exist in the production theme directory (usually located at `../{theme-slug}`).