Theme files#

Snippets can live as files in the theme instead of the database: reviewed in git, deployed with the theme (or pushed with BB Migrate's theme file scope), and identical on every site that runs that theme. They are read-only in the admin (Snippets → Theme files) and print exactly like database snippets.

Where#

snippets/ in the active theme, and in the parent theme when a child theme is active (the child's file wins when both have the same key). The bb_snippets_file_dirs filter changes the folders.

Extension	Language
`.css`	CSS
`.scss`	SASS (SCSS syntax), compiled
`.less`	LESS, compiled
`.js`	JavaScript
`.html`	HTML

Files whose name starts with _ are SASS/LESS partials: never printed, imported by name (@import 'variables' finds _variables.scss).

The header#

Every snippet file starts with a comment holding one Field: value per line. A file without a Snippet: line is not a snippet and is ignored.

/*
 * Snippet: Pricing page tweaks
 * Where: is /product/pricing/
 * Where: starts with /pricing/
 * Output: file
 * Order: 7
 */
.pricing-table { gap: 24px; }

<!--
Snippet: Webinar banner
Where: contains /events/
Position: body
Expires: 2026-12-31
-->
<div class="webinar-banner">…</div>

Field	Values	Default
`Snippet`	The title	required
`Where`	`all`, `homepage`, `contains X`, `not contains X`, `is X`, `is not X`, `starts with X`, `ends with X`, `conditional EXPR`; one per line	none: prints nowhere
`Position`	`head`, `footer`, `body` (HTML, after the opening body tag), `shortcode` (HTML)	`head`
`Output`	`inline`, `file` (CSS/JS)	`inline`
`Devices`	`all`, `desktop`, `mobile` (HTML)	`all`
`Loads on`	Comma list of `site`, `admin`, `login`, `block editor`	`site`
`Order`	`1` (first) to `10`	`5`
`Minify`	`yes`, `no`	`no`
`Environments`	Comma list of `production`, `staging`, `development`, `local`	everywhere
`Expires`	`YYYY-MM-DD`	never
`Critical`	`auto`, `inline`, `defer` (linked files; see Editing)	`auto`
`jQuery`	`auto`, `yes`, `no` (JavaScript)	`auto`
`Active`	`yes`, `no`	`yes`
`Key`	The snippet's key	file name and type, e.g. `pricing-css`
`Shortcode`	Name for `[ccj id="…"]` (HTML, `Position: shortcode`)	the key
`Owner`, `Notes`	Free text

Rules work exactly as in the database: see Where on site. A value the header does not understand is reported on the Theme files page and by wp bb-snippets files, and the default is used.

Within the same order number, database snippets print first (newest first), then theme files by name.

Moving a snippet between the database and the theme#

A database snippet and a theme file with the same key never both print: the database snippet wins and the file is listed with a warning. So both directions are safe at every step.

Database → theme: on the snippet's edit screen, Download as a theme file (or wp bb-snippets to-file <key>) gives the code with every setting in the header. Commit it to snippets/, deploy, then trash the database snippet; the file takes over.
Theme → database: Copy to database on the Theme files page creates a database snippet with the same key, code and settings. It takes over at once; then delete the file from the theme.

When changes show#

A theme file is part of the fingerprint, so an edited, added or removed file is picked up on the next admin page, WP-CLI command or hourly check, and on the front end within five minutes; wp bb-snippets rebuild does it at once. After a BB Migrate theme push, run wp bb-migrate site snippets to rebuild at once (the file push itself loads only BB Migrate). A theme switch rebuilds in the same request. A rebuild from a file change purges the whole page cache.

Theme file snippets print only under BB Snippets; they are left out of the options Simple Custom CSS and JS reads.