DEV Community: Jozef Môstka

Symfony UX: Single Directory Components (SDC) - The Path to Cleaner Architecture Without Tailwind

Jozef Môstka — Wed, 28 Jan 2026 04:39:00 +0000

Frontend development in Symfony has taken a huge leap forward in recent years. Thanks to Symfony UX and Twig Components, we've gained the ability to write reusable components much like in React or Vue. However, the more components you have, the more you encounter one annoying problem: files are scattered across the entire project.

A PHP class in src/Components, a Twig template in templates/components, CSS in assets/styles, and JavaScript somewhere else entirely. When you want to change the color of a button, you're looking at a trip through four different directories.

Some time ago, Hugo Alliaume published a great article A Better Architecture for Your Symfony UX Twig Components, where he proposed the concept of Single Directory Components (SDC). The idea is simple: let's have everything in one folder.

Today, we'll show you how to take this concept to the next level, completely get rid of manual configuration, and maybe even Tailwind.

Why Single Directory Components (SDC)?

If you've ever worked with Angular or Vue, you know that feeling of order. An Alert component is a single folder containing everything essential.

In the SDC approach, it looks like this:

src_component/
└── UI/
    └── Button/
        ├── Button.php           # Logic
        ├── Button.html.twig     # Template
        ├── Button.css           # Styles
        └── Button_controller.js # Interactions (Stimulus)

Main Advantages:

Maintainability: When you no longer need a component, you just delete one folder.
Developer Experience: No context switching between distant folders.
Isolation: Styles and scripts belong only to that one component.

Is Tailwind Passé? The Power of Native CSS and Variables

Lately, there's more and more talk about how, with the arrival of modern CSS features (like CSS variables, nesting, @layer), the need for utility frameworks like Tailwind is decreasing. Articles like The Power of CSS Variables remind us that pure CSS is stronger today than ever before.

The SDC approach plays right into this trend. When you have a CSS file right next to your PHP class, you don't need to write 20 Tailwind classes in your HTML. You can define clean, semantic CSS that uses CSS variables linked directly to PHP logic.

Our Solution: UX SDC Bundle

Hugo's article showed how to set up SDC manually. However, it requires changes to composer.json, Twig configuration, AssetMapper, and Stimulus.

Our bundle tito10047/ux-sdc does it for you. It's a Zero Configuration solution. Just install the bundle and mark the class with an attribute.

#[AsSdcComponent('UI:Button')]
class Button {
    // The bundle automatically finds Button.html.twig, Button.css, and Button_controller.js
}

The "Magic" Inside (Without Performance Loss)

The bundle solves technical challenges that you would have to patch yourself with a manual approach:

Asset Orchestration: CSS and JS files are injected into the page only when the component is actually rendered.
No More "Phantom" Controllers: You don't have to create an empty Stimulus controller just so AssetMapper knows about your CSS. The bundle handles it for you.
HTTP Preload & FOUC: We automatically generate Link headers for HTTP preload. The browser starts downloading CSS even before it starts parsing HTML. This eliminates the annoying flash of unstyled content (FOUC).
Production Performance: Thanks to a compiler pass, no disk scanning happens in production. Everything is pre-prepared in the cache.

Real-world Example: Project "Formalitka"

What does it look like in the real world? Take a look at the project formalitka.mostka.sk. The entire UI kit is built on SDC without a single line of Tailwind.

Let's take their Button component. The PHP class defines properties like color or size. The CSS then processes these properties using variables:

/* Button.css */
@layer components {
    .button {
        background: var(--color-primary);
        color: var(--color-on-primary);
        transition: var(--transition);

        &.button--secondary {
            background: var(--color-secondary);
        }
    }
}

Thanks to SDC, this complex component (containing seal animations, sounds, and special effects) is contained within one directory and is easy to maintain.

How to Get Started?

Installation is lightning fast:

composer require tito10047/ux-sdc

ux_sdc:
    ux_components_dir: '%kernel.project_dir%/src_component'
    component_namespace: 'App\Component'

And add the asset placeholder to your base.html.twig:

<head>
    {{ render_component_assets() }}
</head>

That's it. From this moment on, just create directories and write code.

Performance Under the Microscope: Proof Instead of Promises

When automation and "magic" come into play, the question often arises: What about performance? We put the SDC approach to a stress test with 500 unique components. Here are the key findings from our benchmarks:

Scenario	Classic Approach	SDC Approach	Difference
Warmup (Prod)	583.1 ms	586.2 ms	+3.1 ms
Render (Prod Runtime)	26.5 ms	31.6 ms	+5.1 ms
Render (Dev Runtime)	26.5 ms	88.4 ms	+61.9 ms

What does this mean in practice?

In production, the overhead is almost zero. Thanks to the compiler pass, no disk scanning happens at runtime. Rendering a single component has an overhead of only about 8.8µs, a negligible price for fully automated asset and Stimulus management.
Dev mode is optimized for DX. Instead of having to clear the cache every time a file changes, the bundle in dev mode uses runtime autodiscovery. It scans the disk only for those components that are currently being rendered. This means that if you add a new CSS file or change a Twig template, you see the changes immediately. Thanks to internal metadata caching within a single request, repeated rendering of the same component remains very fast.
Memory Footprint: With 500 components, the bundle consumes about 8MB more memory during container compilation, which is perfectly fine for modern applications.

You can find the full report in our benchmark.md.

The Future and Your Feedback (Version 0.0.1)

This bundle is currently in version 0.0.1. It's an early stage where we're looking for the right path. I wrote this article not only to share our solution but mainly to get feedback from you, the community.

We're interested in:

What do you think about the proposed API?
Is there anything missing that you would expect in an SDC approach?
Do you see any pitfalls in this approach that we've overlooked?

We want this bundle to be built on solid foundations and real developer needs from the first stable version. Every GitHub issue, discussion, or comment moves us forward.

Conclusion

Single Directory Components combined with modern CSS are changing the way we think about Symfony UX. We're getting rid of unnecessary boilerplate code, cleaning up our project structure, and increasing our performance as developers.

Try the UX SDC Bundle and say goodbye to scattered files. The future of Symfony UX is in order and clarity.

The Ultimate Image Solution for Symfony - stop writing srcset manually

Jozef Môstka — Fri, 09 Jan 2026 12:09:12 +0000

Solving the Image Problem in Symfony: Meet PGI

Images are the heaviest part of the modern web. They are responsible for slow page loads, frustrating Cumulative Layout Shift (CLS), and a nightmare developer experience when trying to implement truly responsive designs. If you’ve ever wrestled with complex <picture> tags or manually calculated srcset values for different breakpoints, you know the pain.

Enter PGI (Progressive Image Bundle)—the new standard for image handling in Symfony 6.4 and newer versions.

The Hook: Why Core Web Vitals Changed Everything

Google’s Core Web Vitals—specifically Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS)—have transformed how we build websites. It’s no longer enough to just "show an image." You need to show it fast, and you must ensure the layout doesn’t jump when the image finally appears.

For many Symfony developers, achieving a perfect 100/100 PageSpeed score while maintaining a clean codebase has felt like a trade-off. You either spend hours writing custom responsive logic or you settle for "good enough" performance. PGI was born to eliminate that trade-off.

Code Showcase: From Messy to Masterful

Let’s look at the difference. A standard responsive image in Twig often looks like this:

<img src="{{ asset('images/hero.jpg') }}" 
     srcset="{{ asset('images/hero_sm.jpg') }} 600w, {{ asset('images/hero_lg.jpg') }} 1200w"
     sizes="(max-width: 600px) 100vw, 50vw"
     width="1200" height="675"
     loading="lazy"
     alt="Hero image">

And that’s just for one aspect ratio. With PGI, you get a clean, Tailwind-inspired syntax:

<twig:pgi:Image 
    src="images/hero.jpg" 
    sizes="sm:12@square md:6@landscape"
    alt="Responsive hero image" 
    preload
/>

Real-world Case: just6words.com

To see PGI in action, let's look at how it handles a single image across different devices using an example from just6words.com.

Instead of writing multiple <img> tags or complex <picture> logic, you define everything in one place:

<twig:pgi:Image 
    src="realcase.jpg" 
    sizes="sm:12@square md:6@landscape" 
    alt="Responsive real-world example"
/>

What happens on different devices?

Mobile (sm): The browser loads a Square (1:1) crop. It takes the full width of the container.
Tablet/Desktop (md+): The browser automatically switches to a Landscape (16:9) crop. The image now occupies only half of the grid (6/12 columns).

Rendered HTML (Clean & Semantic)

PGI generates a single, optimized block of HTML that handles all the heavy lifting, including the Blur Placeholder:

<div class="progressive-image-container" 
     style="--img-width-sm: 640px; --img-aspect-sm: 1; --img-width-md: 384px; --img-aspect-md: 1.7777777777778;" ...>
    <canvas data-tito10047--progressive-image-bundle--progressive-image-target="placeholder" ...></canvas>
    <img src="/realcase.jpg" 
         srcset="/media/cache/640x640/realcase.jpg 640w, /media/cache/384x216/realcase.jpg 384w" 
         sizes="(min-width: 768px) 384px, (min-width: 640px) 640px, 100vw" ...>
</div>

What's happening here?

sm:12@square: Full width on small screens, automatically cropped to 1:1.
md:6@landscape: Half width (6/12 columns) from medium breakpoint, automatically cropped to 16:9.
xl:[430x370]: Need a very specific size for a custom layout? PGI supports arbitrary values directly in the sizes attribute.
preload: PGI automatically injects a <link rel="preload"> into your <head>, optimizing your LCP score instantly.

The "Progressive" in PGI: Blur-up Experience

One of the most satisfying features for users is the built-in Blurhash support. Instead of showing a blank space or a generic spinner, PGI renders a beautiful, ultra-lightweight blurred version of the image immediately.

This "blur-up" technique significantly improves perceived performance. Users see the layout and the context of the image instantly, even on slow connections, while the high-resolution version loads in the background. Once ready, the high-res image smoothly fades in, replacing the placeholder.

Technical Deep Dive: Zero CLS and CSS Magic

How does PGI prevent layout shift? It’s not just about adding width and height attributes. PGI leverages modern CSS aspect-ratio and CSS variables.

When the component renders, it calculates the aspect ratio based on your sizes definition. It then wraps the image in a container that reserves the exact space needed. No more content jumping as images load—even if the image is lazy-loaded or slow to arrive.

Powering the Engine: LiipImagine Integration

PGI doesn't reinvent the wheel for image processing. Instead, it stands on the shoulders of a giant: LiipImagineBundle. By default, PGI can delegate the heavy lifting of resizing and filtering to LiipImagine, allowing you to leverage its full ecosystem.

One of the most powerful features of this synergy is the automatic conversion to modern formats like WebP. With just a few lines of configuration, you can ensure that every image served by PGI is not only perfectly sized but also perfectly compressed.

Example Configuration:

# config/packages/liip_imagine.yaml
liip_imagine:
    default_filter_set_settings:
        format: webp
    webp:
        generate: true

# config/packages/progressive_image.yaml
progressive_image:
    image_configs:
        quality: 75
        post_processors:
            cwebp: { q: 30 }

By using the liip_imagine decorator, PGI automatically routes image requests through LiipImagine's filter system. This means you can use all your existing Liip filters while benefiting from PGI's superior Twig syntax and Zero CLS features.

Under the Hood: The Configuration That Makes It Possible

One of the most praised aspects of PGI is its flexibility. While it works out-of-the-box, the real power lies in its configuration. Let’s break down the most important parts of progressive_image.yaml:

# config/packages/progressive_image.yaml
progressive_image:
    # 1. Responsive Strategy
    responsive_strategy:
        grid:
            framework: tailwind # or bootstrap, or custom
        ratios:
            landscape: "16/9"
            square: "1/1"
            hero: "21/9"

    # 2. Resolvers (Where are your images?)
    resolvers:
        public_files:
            type: "filesystem"
            roots: [ '%kernel.project_dir%/public' ]
        assets:
            type: "asset_mapper"

    # 3. Transparent HTML Caching
    image_cache_enabled: true
    image_cache_service: "cache.app"

1. Responsive Strategy

This is the brain of PGI. By telling the bundle you use Tailwind or Bootstrap, it automatically knows the container widths for every breakpoint. When you say md:6, PGI looks up the md container width, divides it by 2 (6/12 columns), and generates the exact image size needed.

2. Resolvers: File Freedom

Whether you keep your images in the public/ folder or use the modern Symfony AssetMapper, PGI can find them. You can even define a chain resolver to look in multiple places. This is a lifesaver for projects transitioning to newer Symfony features.

3. Performance First: HTML Caching

Generating Blurhash and reading metadata requires CPU power. PGI solves this with transparent HTML caching. Once a component is rendered, the final HTML is stored in your cache. The next time someone visits the page, PGI serves the cached HTML instantly, skipping all PHP logic.

Point of Interest (PoI) Cropping

One of the coolest features is "Smart Cropping." Instead of blindly cropping from the center, you can define a Point of Interest:

<twig:pgi:Image src="team.jpg" pointInterest="75x25" sizes="md:6@square" />

This ensures that the most important part of the image (like a person's face) stays in the frame, regardless of whether it's being cropped to a square, portrait, or landscape ratio.

Why PGI Belongs in Your Next Project

PGI isn't just a wrapper; it's a complete ecosystem for Symfony:

Zero Configuration: Install and it just works with Bootstrap or Tailwind.
Automatic Generation: It generates all required sizes on the fly and caches them.
LiipImagine Integration: It plays nice with existing tools if you need custom filters.
Transparent Caching: It can cache the resulting HTML to avoid re-calculating metadata on every request.

If you are building a modern Symfony application and care about SEO, UX, and your own sanity as a developer, PGI is the missing piece of the puzzle. It’s already powering high-performance sites like just6words.com, helping them achieve near-perfect PageSpeed scores.

Ready to boost your PageSpeed?
Check out PGI on GitHub and join the movement toward a faster, more stable web.