Files

Every file in a snippet’s folder, including files in nested folders, loads by its extension once the folder holds a snippet.json:

Other files, such as a README.md or images, are kept but never loaded.

Without per-file options every file follows the snippet’s configuration: PHP on the snippet’s hook, stylesheets and scripts in its contexts, all of them under its conditions.

PHP files

Every .php file in the folder runs, nested ones included, so keep files that must not run on their own, such as templates you include from other code, outside the snippet folder. A PHP file runs only when its very first characters are <?php; a file that starts with whitespace or a byte order mark, or is empty, is skipped. The guard Byte puts in front of a file that starts outside PHP does not count, so a template still never runs on its own. Each file is included once per request.

Byte writes every PHP file with defined('ABSPATH') || exit; as its first statement, so the file runs nothing when its URL is requested outside WordPress; Sources says where the line goes.

Byte keeps the list of snippets, their files and their snippet.json settings between requests and reads the folders again only when one changes: when Byte writes or deletes a file, or when a folder or a snippet.json changes on disk, so files you add or edit over SFTP or Git show on the next request.

SCSS files

SCSS compiles on the server, and the compiled CSS is cached in uploads/sleek-byte/scss-cache. The cache is rebuilt when the file is newer than its cached CSS; a change to a partial alone does not rebuild the files that import it, so save those too.

A file whose name starts with an underscore, such as _variables.scss, is a partial: it is never enqueued on its own, but other SCSS files import it. Imports resolve against the file’s own folder and the folder above it. A file that fails to compile is not enqueued, and the compiler’s error goes to an error log of its own rather than the snippet’s runtime log.

Handles and dependencies

Byte registers every CSS, SCSS and JavaScript file under the handle sleek-byte-<snippet>-<file>: <snippet> is the snippet’s folder path inside its source, sanitised like a post slug with each slash turned into a hyphen, and <file> is the file name without its extension. In a snippet folder named checkout-tweaks, assets/base.css is sleek-byte-checkout-tweaks-base, and another file can depend on it:

{
  "files": {
    "assets/base.css": {},
    "assets/enhanced.css": {
      "dependencies": ["sleek-byte-checkout-tweaks-base"]
    },
    "assets/interactive.js": {
      "dependencies": ["jquery", "wp-api"]
    },
    "assets/modern.js": {
      "module": true
    }
  }
}

Two files of the same name in one snippet, such as a/style.css and b/style.css, share a handle and only one of them loads, so give them distinct names.

Organising a snippet

Byte reads any folder structure, so group the files by what they do:

woocommerce-extras/
├── assets/
│   ├── checkout.css
│   └── checkout-validation.js
├── includes/
│   ├── cart-functions.php
│   └── checkout-hooks.php
├── index.php
└── snippet.json

{
  "name": "WooCommerce extras",
  "files": {
    "includes/checkout-hooks.php": { "hook": "wp" },
    "assets/checkout-validation.js": { "dependencies": ["jquery"] }
  }
}

Start without files and add an entry only for a file that needs to load differently from the rest of its snippet.