Assets and SCSS System

Flute CMS uses the TemplateAssets class to manage SCSS/CSS resources with automatic compilation via ScssPhp, caching, and theme support. The system is integrated with the @at() directive for including resources in templates.

Core Features:

Contexts main and admin (defined during Template/TemplateAssets initialization)
SCSS compilation → public/assets/css/cache/*, minify depends on config('assets.minify')
Import paths are added automatically for app and active themes; loadScss()/registerScss() connects files and adds their directory path
@at(path, urlOnly = false) directive creates <link>/<script>/<img> tag or returns URL if second parameter is true

Module Assets Structure

SCSS Architecture

Theme CSS Variables

Flute CMS uses CSS variables for themes with light/dark mode support:


// app/Themes/standard/assets/sass/theme/_variables.scss
 
:root {
    --transition: .2s;
    --shadow-small: 0 0px 10px rgba(0, 0, 0, 0.1);
    --shadow-medium: 0 0px 15px rgba(0, 0, 0, 0.15);
    --shadow-large: 0 0px 25px rgba(0, 0, 0, 0.15);
}
 
:root[data-theme=light] {
    --text: #1d1d1f;
    --background: #ffffff;
    --primary: #1d1d1f;
    --secondary: #f5f5f7;
    --accent: #34c759;
    
    --success: #30d158;
    --error: #ff3b30;
    --warning: #ff9500;
    --info: #5ac8fa;
    
    --text-50: #1d1d1f;
    --text-100: #2c2c2e;
    // ... color gradation
    --text-950: #f2f2f7;
}
 
:root[data-theme=dark] {
    --text: #f2f2f7;
    --background: #1c1c1e;
    --primary: #f2f2f7;
    --secondary: #2c2c2e;
    --accent: #A5FF75;
    // ... dark theme
}

SCSS File Structure

Flute CMS uses a modular SCSS architecture with clear separation:


// app/Themes/standard/assets/sass/app.scss
 
@import 'theme/variables';       // Theme variables
@import 'utils/animations';      // Animation utilities
 
@import 'base/reset';           // Style reset
@import 'base/typography';      // Typography
 
@import 'layouts/app';          // App layout
@import 'layouts/header';       // Header
@import 'layouts/footer';       // Footer
 
@import 'components/card';      // Components
@import 'components/buttons';
@import 'components/modals';
@import 'components/tabs';
 
@import 'partials/loading';     // Partial blocks
@import 'partials/breadcrumb';
@import 'partials/notifications';
 
@import 'pages/home';          // Pages
@import 'pages/profile';
@import 'pages/login';
 
@import 'widgets/recent-payments';  // Widgets
@import 'widgets/users-online';

SCSS Components

Real examples of components from the standard theme:


// app/Themes/standard/assets/sass/components/_card.scss
 
.card {
    background: var(--background);
    border: 1px solid var(--transp-1);
    border-radius: 8px;
    padding: 16px;
    transition: var(--transition);
 
    &:hover {
        box-shadow: var(--shadow-medium);
    }
}
 
// app/Themes/standard/assets/sass/components/_buttons.scss
 
.btn {
    display: inline-flex;
    align-items: center;
    padding: 8px 16px;
    border-radius: 6px;
    border: none;
    transition: var(--transition);
    cursor: pointer;
 
    &.btn-primary {
        background: var(--accent);
        color: var(--background);
    }
 
    &.btn-secondary {
        background: var(--secondary);
        color: var(--text);
    }
}
 
// app/Themes/standard/assets/sass/components/_modal.scss
 
.modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.5);
    z-index: 1000;
 
    .modal-content {
        background: var(--background);
        border-radius: 8px;
        box-shadow: var(--shadow-large);
        max-width: 500px;
        margin: 50px auto;
    }
}

Registering SCSS in Module

Using loadScss in Provider


<?php
namespace Flute\Modules\News\Providers;
 
use Flute\Core\Support\ModuleServiceProvider;
 
class NewsProvider extends ModuleServiceProvider
{
    protected ?string $moduleName = 'News';
 
    public function boot(\DI\Container $container): void
    {
        $this->bootstrapModule();
 
        // Register module SCSS file
        $this->loadScss('Resources/assets/scss/news.scss');
    }
}

@at() Directive in Templates


{{-- Include SCSS/CSS resources in templates --}}
@at('Themes/standard/assets/sass/app.scss')
@at('Modules/News/Resources/assets/scss/news.scss')
 
{{-- Include JavaScript --}}
@at('Themes/standard/assets/scripts/app.js')
@at('assets/js/libs/jquery.js')
 
{{-- Include Images --}}
<img src="@at('Themes/standard/assets/images/logo.png')" alt="Logo">
 
{{-- Only URL without tag --}}
<link rel="preload" href="@at('assets/fonts/montserrat/montserrat.css', true)" as="style">

You can clear style/path cache via template()->getTemplateAssets()->clearStyleCache() (deletes public/assets/css/cache/* and internal caches).

Caching and Compilation

TemplateAssets Class

The system automatically compiles SCSS via TemplateAssets:


<?php
// Main TemplateAssets methods
class TemplateAssets
{
    // Add SCSS file for compilation
    public function addScssFile(string $filePath, string $context = 'main'): void
    
    // Add import path
    public function addImportPath(string $path, string $context = 'main'): void
    
    // Process @at() directive
    public function assetFunction(string $expression, bool $urlOnly = false): string
    
    // Compile SCSS to CSS
    private function compileScss(array $scssContents): string
}

Resource Caching


// Automatic CSS file caching
// Path: public/assets/css/cache/{hash}.css
 
// System uses hashes for versioning:
// - SCSS file change = new hash = cache bypass
// - In production cache is valid until files change
// - In development recompilation on every request

Theme Support

theme.json Configuration

Themes can override resources via theme.json:


{
    "name": "Standard",
    "version": "1.0.0",
    "asset_replacements": {
        "Modules/News/Resources/assets/scss/news.scss": "Themes/custom/assets/sass/news-override.scss"
    },
    "asset_wildcard_replacements": {
        "Modules/*/Resources/assets/scss/*": "Themes/custom/assets/sass/modules/*"
    }
}

Fallback System


<?php
// System automatically searches files in order:
// 1. Current theme: app/Themes/custom/assets/sass/news.scss
// 2. Standard theme: app/Themes/standard/assets/sass/news.scss
// 3. Module: app/Modules/News/Resources/assets/scss/news.scss

Best Practices

Using CSS Variables


// app/Modules/News/Resources/assets/scss/news.scss
 
.news-card {
    background: var(--background);
    border: 1px solid var(--transp-1);
    border-radius: 8px;
    color: var(--text);
    
    &:hover {
        box-shadow: var(--shadow-medium);
    }
}
 
.news-title {
    color: var(--accent);
    font-size: 1.25rem;
    font-weight: 600;
}

Modular Organization

One SCSS file per module — Resources/assets/scss/module-name.scss
Use existing variables from theme/_variables.scss
Minimal styles — only unique to the module
Responsiveness — use CSS variables for themes

Performance


// ✅ Good — use theme variables
.my-component {
    background: var(--background);
    color: var(--text);
}
 
// ❌ Bad — hardcoded colors
.my-component {
    background: #ffffff;
    color: #000000;
}

Debugging


<?php
// Enable debug mode for SCSS
// In config/assets.php:
'minify' => false,  // Disable minification
'debug' => true,    // Enable debug
 
// SCSS compilation logs available in:
// storage/logs/templates.log

Conclusion

The Flute CMS asset system provides:

Automatic compilation of SCSS to CSS
Caching for high performance
Theme support with fallback system
CSS variables for adaptability
Simple integration via loadScss() and @at()

Use existing theme variables and follow modular architecture to create compatible and performant styles.