Troubleshooting

Common issues and solutions for WPZylos Assets.

Script Not Loading

Symptom: Script registered but not appearing on page.

Causes:

• Wrong location (admin() on frontend or vice versa)
• condition() returning false
• onPage() hook mismatch
• Dependency not registered

Solution:

// Check location
$assets->script('app')->src('...'); // defaults to 'both'

// Verify admin hook name
add_action('admin_enqueue_scripts', function ($hook) {
    error_log('Current admin hook: ' . $hook);
});

Vite HMR Not Working

Symptom: Assets loading from built files instead of dev server.

Causes:

• Vite dev server not running (npm run dev)
• hot file not present or wrong URL
• WPZYLOS_VITE_DEV_SERVER constant not set

Solution:

# Start Vite dev server
npm run dev

# Check hot file
cat dist/hot
# Should output: http://localhost:5173

Handle Conflicts

Symptom: Asset overridden by another plugin.

Cause: Using generic handle names without prefix.

Solution: WPZylos automatically prefixes handles via ContextInterface::assetHandle(). Never use wp_enqueue_script() directly.

Inline Script Position

Symptom: Inline script runs before the main script.

Solution: Inline scripts are added with position 'after' by default. If you need it before:

// Add inline before the script
wp_add_inline_script($handle, $code, 'before');

manifest.json Not Found

Symptom: ViteAssetResolver returns null.

Causes:

• Build not run (npm run build)
• Manifest path changed in Vite config

Solution:

npm run build
ls dist/.vite/manifest.json

Module Script CORS Errors

Symptom: type="module" scripts blocked by CORS.

Solution: Ensure your dev server allows the WordPress domain:

// vite.config.js
export default defineConfig({
  server: {
    cors: true,
    origin: 'http://localhost:5173',
  },
});