claude-websimple-devops/references/wp-assets.md

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:

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:

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:

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:

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.