https://github.com/sebobo/shel.criticalcss
Allow adding and combining inline (scoped) styles in Neos CMS
https://github.com/sebobo/shel.criticalcss
critical-css hacktoberfest inline-styles neos-cms
Last synced: 2 months ago
JSON representation
Allow adding and combining inline (scoped) styles in Neos CMS
- Host: GitHub
- URL: https://github.com/sebobo/shel.criticalcss
- Owner: Sebobo
- License: gpl-3.0
- Created: 2019-11-05T14:51:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-03T13:43:17.000Z (3 months ago)
- Last Synced: 2025-04-03T14:38:09.372Z (3 months ago)
- Topics: critical-css, hacktoberfest, inline-styles, neos-cms
- Language: PHP
- Homepage:
- Size: 85.9 KB
- Stars: 10
- Watchers: 3
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
README
# Adding and combining inline styles for critical CSS in Neos CMS
[](https://packagist.org/packages/shel/critical-css)
[](https://packagist.org/packages/shel/critical-css)
[](https://travis-ci.org/Sebobo/Shel.CriticalCSS)
[](https://styleci.io/repos/219770230)
This package provides several helpers to allow adding inline styles to Fusion components in Neos CMS
and combining them locally or into the head of a html document.
The styles are automatically scoped by default and can be defined dynamically like any other Fusion object.
CSS classes are dynamically generated based on the hash of the defined styles.
This allows you to keep styles together with a component in one file and also be able to override them.
A good use case for this is to define inline styles for your critical CSS that should be loaded instantly when
the site is shown and defer loading other styles that are not needed immediately.
Use cases:
* Define critical CSS that should be available for "above the fold" content.
* Define dynamic CSS variables for themed websites.
* Include CSS with reusable components.
* Have a minimal set of CSS for each individual page.
Supported:
* Scoped styles
* Style nesting
* Global styles with specific selectors
* Automatic style merging into document head via http component
* `@media` and `@supports` queries
This package doesn't require any specific browser features.
The inspiration for this package came from [SvelteJS](https://svelte.dev) and [JSS](https://cssinjs.org).
Table of contents
* [Installation](#installation)
* [Usage](#usage)
* [Adding inline styles](#adding-inline-styles)
* [Nesting styles](#nesting-styles)
* [Using multiple styles in one component](#using-multiple-styles-in-one-component)
* [Using the shorthand Fusion helper](#using-the-shorthand-fusion-helper)
* [Modifying styles with props](#modifying-styles-with-props)
* [Usage with CSS variables](#usage-with-css-variables)
* [Custom selectors](#custom-selectors)
* [Insert styles from a file](#insert-styles-from-a-file)
* [Other examples](#other-examples)
* [Modifying the styles collector behaviour](#-modifying-the-styles-collector-behaviour)
* [Fusion based style collector](#fusion-based-style-collector)
* [Limitations](#limitations)
* [Inserting new elements in the Neos UI](#inserting-new-elements-in-the-neos-ui)
## Installation
Run this in your site package:
composer require --no-update shel/critical-css
Then run `composer update` in your project root.
## Usage
### Adding inline styles
Given the following example component:
prototype(My.Site:Component.Blockquote) < prototype(Neos.Fusion:Component) {
text = ''
renderer = afx`
{props.text}
`
@process.styles = Shel.CriticalCSS:Styles {
font-size = '2em'
font-family = 'Comic Sans'
padding = '.5rem'
}
}
The resulting HTML will look similar to this:
.style--cd7c679e3d{font-size:2m;font-family:Comic Sans;padding:.5rem;}
My text
This will already work but you will have a lot of style tags this way and possible duplicates.
This package automatically applies a "style collector" to the document which collects all these inline styles.
So all style tags will first collected, then merged into one list, duplicates removed and inserted into the HTML head
as one style tag.
Be careful when applying the styles not only to one tag but to a group of tags. Then it will
automatically generate a wrapping tag similar to how the Augmenter in Fusion works.
#### Nesting styles
Again a similar example but with nested styles
prototype(My.Site:Component.Blockquote) < prototype(Neos.Fusion:Component) {
text = ''
link = ''
renderer = afx`
{props.text}
Read more
`
@process.styles = Shel.CriticalCSS:Styles {
font-size = '2em'
font-family = 'Comic Sans'
padding = '.5rem'
a {
color = 'blue'
text-decoration = 'underline'
}
}
}
When nesting you can either use `Neos.Fusion:DataStructure` or simple nesting with braces like in the example.
The resulting HTML will look similar to this:
.style--cd7c679e3d{font-size:2m;font-family:Comic Sans;padding:.5rem;}.style--cd7c679e3d a{color:blue;text-decoration:underline;}
My text
#### Using multiple styles in one component
To style several parts of a component you can do the following:
prototype(My.Site:Component.Complex) < prototype(Neos.Fusion:Component) {
headline = ''
text = ''
footer = ''
renderer = afx`
{props.headline}
{props.text}
{props.footer}
`
@process.styles = Shel.CriticalCSS:Styles {
padding = '.5rem'
div {
margin = '1rem 0'
}
}
}
This will result in three style tags with three different css classes. All of them will be picked up
by the collector.
#### Using the shorthand Fusion helper
Somewhere in your package define the short prototype:
prototype(CSS:Style) < prototype(Shel.CriticalCSS:Styles)
(Note the needed colon: `CSS`**`:`**`Style`. Fusion doesn't mind, but afx would convert `CssStyle` to a `Neos.Fusion:Tag`. Afx needs a way to differentiate.)
Then you can write the previous example like this:
prototype(My.Site:Component.Complex) < prototype(Neos.Fusion:Component) {
headline = ''
text = ''
footer = ''
renderer = afx`
{props.headline}
{props.text}
{props.footer}
`
@process.styles = CSS:Style {
padding = '.5rem'
div {
margin = '1rem 0'
}
}
}
#### Modifying styles with props
This method allows you to modify styles easily by using props:
prototype(My.Site:Component.TextBanner) < prototype(Neos.Fusion:Component) {
text = ''
backgroundColor = '#4444ff'
renderer = afx`
{props.text}
`
}
Remember you can only access the props when the styles object is applied somewhere inside the `renderer`.
You can do this either via `[email protected]` or like in the example code.
#### Usage with CSS variables
You can also easily define global or local CSS variables this way:
prototype(My.Site:Document.Page) < prototype(Neos.Neos:Page) {
body {
content {
main = Neos.Neos:PrimaryContent {
nodePath = 'main'
@process.styles = Shel.CriticalCSS:Styles {
--theme-background = ${q(site).property('themeBackground')}
--theme-color = ${q(site).property('themeColor')}
}
}
}
}
}
And when you then have a nested component like this:
prototype(My.Site:Component.Blockquote) < prototype(Neos.Fusion:Component) {
text = ''
renderer = afx`
{props.text}
`
@process.styles = Shel.CriticalCSS:Styles {
color = 'var(--theme-color)'
}
}
I can recommend to use my [colorpicker](https://github.com/Sebobo/Shel.Neos.ColorPicker) for Neos CMS when
allowing an editor to define a theme and then put those values into CSS variables.
#### Custom selectors
It's also possible to use custom selectors to target the `html`, `body` or all tags `*`:
prototype(Neos.Neos:Page) {
body {
@process.globalStyles = Neos.Fusion:Join {
all = Shel.CriticalCSS:Styles {
selector = '*'
box-sizing = 'border-box'
}
body = Shel.CriticalCSS:Styles {
selector = 'body'
background-color = 'blue'
}
}
}
}
#### Insert styles from a file
The package has a Fusion helper to insert styles inline from a file.
Do scoping is done, but the style tag will be picked up by the style collector.
prototype(My.Site:Component.Test) < prototype(Neos.Fusion:Component) {
text = ''
renderer = afx`
{props.text}
`
}
Also works as `process`:
prototype(My.Site:Component.Test) < prototype(Neos.Fusion:Component) {
text = ''
renderer = afx`
{props.text}
`
@process.addStyles = Shel.CriticalCSS:LoadStyles {
path="resource://My.Site/Private/Fusion/Components/Test/style.css"
}
}
#### Other examples
You can also take a look at the [functional test fixtures](Tests/Functional/Fixtures/Fusion/Styles.fusion) to see the verified use cases.
### Modifying the styles collector behaviour
By default the collector is applied as http middleware at the end of the request chain.
It will merge all inline styles generated with this package into one style tag in the html head.
Duplicates are removed during this process.
You can disable this behaviour with this setting:
Shel:
CriticalCSS:
mergeStyles:
enabled: false
#### Fusion based style collector
This package contains a second collection method via Fusion.
The `Shel.CriticalCSS:StyleCollector` helper can be used in a similar way as `process` to merge
all inline style tags into one. When doing this inside the DOM the style tag will be prepended wherever
it is applied to. When applying it to the whole document, it will also merge the styles into the html head.
This method can be helpful in certain cases but has issues when the contained components have
their own cache configurations. This is why the http component is preferred to solve this on the
document level. But if for some reason you cannot use the default, this might help.
### Limitations
#### Inserting new elements in the Neos UI
When working the backend the styles collector will not automatically pick up style blocks from newly inserted elements.
This might cause some issues when the added elements are somehow treated with Javascript like in Sliders.
#### Caching
As explained in the styles collector section, the Fusion based collector has issues with cached components that
have styles applied to them. This can result in styles missing from the document.