symfony-frontend

name

symfony-frontend

description

Handle CSS and JavaScript in a Symfony 8.1 app. Use whenever you add, build, reference, version, or debug front-end assets: AssetMapper (recommended, no build step, importmap.php, importmap:require, asset-map:compile), Webpack Encore (Node-based alternative, npm run dev/build), Stimulus controllers, Symfony UX, Turbo, Tailwind or Sass, or the asset() / importmap() Twig functions. Trigger on requests like "add a JS library", "load my CSS", "use Tailwind", "set up Stimulus", "compile assets for production", "version my images", or any mention of assets, importmap, Encore, Stimulus, UX, or Turbo.

Manage Symfony-served CSS, JavaScript, and assets via AssetMapper or Webpack Encore.

Use this skill when

• Referencing images/fonts/files from Twig with asset().
• Adding a third-party JS/CSS package (bootstrap, lodash, etc.).
• Loading your own JavaScript or CSS in a page.
• Setting up Stimulus, Symfony UX, or Turbo.
• Adding Tailwind or Sass.
• Compiling or versioning assets for production deployment.

Do not use this skill when

• The UI is owned by a SEPARATE frontend app (React/Vue/Svelte) served by its own tooling (Vite, Next, etc.). In that case the assets live in that app, not in Symfony. Only use this skill for assets that Symfony itself serves.
• You are doing pure backend/API work with no Twig templates or served assets.

Instructions

1. DETECT the existing build system first. Run ls importmap.php webpack.config.js.
   • importmap.php exists -> AssetMapper. Open references/asset-mapper.md.
   • webpack.config.js exists -> Webpack Encore. Open references/webpack-encore.md.
   • Neither exists and assets are needed -> AssetMapper is recommended; install it per references/asset-mapper.md.
2. PRESERVE the detected choice. Do NOT switch AssetMapper <-> Encore. Do NOT install both. If asked to switch, confirm with the user before changing.
3. Open exactly ONE reference file for the task at hand (see "Reference files"). Read it, then do the smallest change that satisfies the request.
4. For Stimulus / Symfony UX / Turbo work, open references/stimulus-ux.md.
5. Make the change. Reference assets in Twig with asset('logical/path').
6. STOP when the asset loads correctly in the browser (or asset-map:compile for AssetMapper / npm run build for Encore succeeds without error). Do not keep adding configuration, optimizations, or extra packages beyond the request.

Done criteria: the requested asset/package/controller is referenced and loads; the build command (if any) exits 0. Then stop.

Reference files

• references/asset-mapper.md — open when the project uses AssetMapper (or none yet): install, importmap.php, importmap:require/install/remove/update, asset(), importmap('app'), handling CSS, asset-map:compile, Tailwind/Sass.
• references/webpack-encore.md — open when webpack.config.js exists: install, webpack.config.js, entries, encore_entry_*_tags, npm run dev/watch/build, Sass/TypeScript/React.
• references/stimulus-ux.md — open for Stimulus controllers, Symfony UX bundles, Turbo, and passing data from Twig to JavaScript.