156 lines
5.9 KiB
Markdown
156 lines
5.9 KiB
Markdown
# WP Assets
|
|
|
|
Use this skill for Websimple WordPress theme asset source, build, and enqueue conventions.
|
|
|
|
Use `references/wp-theme-dev.md` for general PHP/theme structure, `references/wp-code-style.md` for PHP linting, and `references/wp-browser.md` for visual smoke tests.
|
|
|
|
## Core principles
|
|
|
|
- Keep build-time source assets under `src/`.
|
|
- Do not edit compiled/generated assets unless the user explicitly asks and there is no source available.
|
|
- Detect the project's actual pipeline before changing files.
|
|
- Preserve the existing asset toolchain unless the user asks for migration.
|
|
- Keep PHP enqueue integration aligned with the build output and manifest strategy.
|
|
|
|
## Source structure
|
|
|
|
Theme source assets should live under `src/` with clear subdirectories for frontend concerns.
|
|
|
|
Common structure:
|
|
|
|
```text
|
|
src/
|
|
styles/ # CSS/SCSS source
|
|
scripts/ # JavaScript/TypeScript entrypoints and modules
|
|
components/ # Vue/React or shared frontend components
|
|
images/ # source images/icons when processed by the build
|
|
fonts/ # source fonts when processed by the build
|
|
```
|
|
|
|
Follow the existing project structure first. Do not reorganize assets broadly without approval.
|
|
|
|
## Detect the pipeline
|
|
|
|
Before editing assets, inspect the theme root for signals:
|
|
|
|
```text
|
|
package.json
|
|
vite.config.*
|
|
webpack.config.*
|
|
webpack.mix.js
|
|
postcss.config.*
|
|
tailwind.config.*
|
|
tsconfig.json
|
|
src/
|
|
assets/
|
|
dist/
|
|
```
|
|
|
|
Use `package.json` scripts as the source of truth for build/dev commands.
|
|
|
|
Common signals:
|
|
|
|
- Vite: `vite.config.ts`, scripts like `dev`, `build`, `preview`.
|
|
- Legacy webpack/Mix: `webpack.config.js`, `webpack.mix.js`, scripts using `webpack`, `mix`, or older build tooling.
|
|
- Plain scripts/styles: source under `src/` with minimal bundler config.
|
|
|
|
If signals conflict, report the ambiguity before changing build config.
|
|
|
|
## Build output
|
|
|
|
Treat build output as generated unless the project clearly uses checked-in compiled assets.
|
|
|
|
Common output directories:
|
|
|
|
```text
|
|
assets/
|
|
dist/
|
|
```
|
|
|
|
Compiled/generated assets should normally be excluded from Git. For new or modernized projects, prefer ignoring generated build output and committing only source/config files.
|
|
|
|
Legacy projects may already commit compiled assets. Do not remove those generated files or change `.gitignore` behavior without approval. For those projects, keep the committed-build convention and make sure to run the build before committing so generated assets stay in sync with source changes.
|
|
|
|
Do not edit minified files, hashed files, generated manifests, compiled CSS/JS, source maps, or copied vendor assets directly when source files exist.
|
|
|
|
If compiled assets are committed in the project, update them by running the project build instead of manual edits.
|
|
|
|
## Vite conventions
|
|
|
|
For Vite-based themes:
|
|
|
|
- inspect `vite.config.*` before adding entrypoints;
|
|
- keep entrypoints under `src/`;
|
|
- preserve existing manifest/output settings;
|
|
- use the manifest when PHP enqueue code relies on hashed filenames;
|
|
- run the project build after changing source assets when verification requires compiled output.
|
|
|
|
Do not rewrite Vite config or migrate legacy projects to Vite unless explicitly requested.
|
|
|
|
## Legacy webpack conventions
|
|
|
|
For legacy webpack/Mix themes:
|
|
|
|
- inspect `webpack.config.*` or `webpack.mix.js` first;
|
|
- preserve existing entrypoint names and output paths;
|
|
- avoid modernizing syntax or build tooling as part of unrelated changes;
|
|
- run the existing build script when compiled assets must be refreshed.
|
|
|
|
Do not convert webpack/Mix to Vite without an explicit migration request.
|
|
|
|
## Enqueue integration
|
|
|
|
Asset enqueue logic usually belongs under theme PHP includes, often `includes/core/assets.php` or the existing project equivalent.
|
|
|
|
Before changing enqueue code:
|
|
|
|
1. Identify the build output path.
|
|
2. Identify whether filenames are stable or hashed.
|
|
3. Identify whether the theme uses a manifest.
|
|
4. Preserve existing handles, dependencies, script type/module settings, and localization/global variables unless changing them is required.
|
|
|
|
For stable filenames, filemtime-based cache busting is acceptable when already used by the project:
|
|
|
|
```php
|
|
wp_enqueue_style(
|
|
'example-theme',
|
|
get_stylesheet_directory_uri() . '/dist/css/theme.css',
|
|
[],
|
|
filemtime( get_stylesheet_directory() . '/dist/css/theme.css' )
|
|
);
|
|
```
|
|
|
|
For hashed filenames, read from the manifest rather than hardcoding generated names.
|
|
|
|
## Vue and React source
|
|
|
|
Vue/React source should still live under `src/`, typically under `src/components/` or an existing frontend app directory.
|
|
|
|
Keep this skill focused on source placement and build integration. For component architecture, state management, app mounting, or framework-specific conventions, use dedicated future `wp-vue` or `wp-react` guidance.
|
|
|
|
## Styling conventions
|
|
|
|
- Keep styles under `src/styles/` or the existing style source directory.
|
|
- Preserve the project's CSS methodology and naming conventions.
|
|
- Avoid broad restyling when the user asked for a targeted fix.
|
|
- Prefer source-level changes over compiled CSS edits.
|
|
|
|
## Workflow
|
|
|
|
1. Inspect theme root, `package.json`, build config, source directories, output directories, and enqueue PHP.
|
|
2. Determine whether the project uses Vite, webpack/Mix, or another pipeline.
|
|
3. Edit source files under `src/` or the established source directory.
|
|
4. Do not touch generated output manually.
|
|
5. Run the smallest relevant check: build, typecheck, lint, or targeted frontend smoke test.
|
|
6. If compiled assets are committed, run the build before committing and inspect generated diffs.
|
|
7. Use `references/wp-browser.md` to verify visible frontend changes.
|
|
8. Report changed source files, generated files, and any build/verification blockers.
|
|
|
|
## Safety
|
|
|
|
- Do not run package installs or major upgrades without approval.
|
|
- Do not migrate build tools without explicit request.
|
|
- Do not edit compiled/minified/generated assets directly when source exists.
|
|
- Do not remove legacy build config just because a newer tool would be nicer.
|
|
- Watch for large generated diffs and call them out before committing.
|