Documentation
¶
Overview ¶
Package postcss provides a PostCSS plugin for GoSPA with Tailwind CSS v4 support. It processes CSS through PostCSS with configurable plugins.
Index ¶
- func AsyncCSS(path string) string
- func AsyncCSSWithNonce(path, nonce string) string
- func CriticalCSS(path string) string
- func CriticalCSSWithFallback(path, fallback string) string
- func CriticalCSSWithNonce(path, nonce string) string
- func GenerateAsyncCSSScript(cssPath string) stringdeprecated
- func GenerateAsyncCSSScriptWithNonce(cssPath, nonce string) string
- func GenerateCriticalCSSHelper(projectDir, criticalCSSPath string) (string, error)
- type BundleEntry
- type Config
- type CriticalCSSConfig
- type Dimension
- type PluginConfig
- type PostCSSPlugin
- func (p *PostCSSPlugin) Commands() []plugin.Command
- func (p *PostCSSPlugin) Dependencies() []plugin.Dependency
- func (p *PostCSSPlugin) GetConfig() *Config
- func (p *PostCSSPlugin) Init() error
- func (p *PostCSSPlugin) Name() string
- func (p *PostCSSPlugin) OnHook(hook plugin.Hook, ctx map[string]interface{}) error
- func (p *PostCSSPlugin) SetConfig(cfg *Config)
- func (p *PostCSSPlugin) Stop()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsyncCSS ¶ added in v0.1.16
AsyncCSS generates the HTML markup for async loading non-critical CSS. This is a template helper that can be used directly in templ files. Usage in templates: @templ.Raw(AsyncCSS("/static/css/non-critical.css")) Note: use AsyncCSSWithNonce when a nonce-based CSP is active.
func AsyncCSSWithNonce ¶ added in v0.1.36
AsyncCSSWithNonce is like AsyncCSS but stamps the emitted <script> with the provided CSP nonce so it passes a strict nonce-based Content-Security-Policy. Usage in templates: @templ.Raw(postcss.AsyncCSSWithNonce("/static/css/non-critical.css", gospatempl.GetNonce(ctx)))
func CriticalCSS ¶ added in v0.1.16
CriticalCSS reads the critical CSS file and returns its content for inlining in templates. This is a template helper that can be used directly in templ files. Usage in templates: @CriticalCSS("./static/css/critical.css")
func CriticalCSSWithFallback ¶ added in v0.1.16
CriticalCSSWithFallback returns critical CSS from the given path, or returns a fallback message if the file doesn't exist. Useful for development where critical CSS might not be extracted yet.
func CriticalCSSWithNonce ¶ added in v0.1.37
CriticalCSSWithNonce generates a <style> tag with the critical CSS and a CSP nonce. This is preferred over using <style nonce={...}>@templ.Raw(CriticalCSS(...))</style> because Templ treats the content of <style> tags as raw text and may not execute the @ component declaration correctly.
func GenerateAsyncCSSScript
deprecated
added in
v0.1.16
func GenerateAsyncCSSScriptWithNonce ¶ added in v0.1.36
GenerateAsyncCSSScriptWithNonce generates a CSP-compliant async CSS loader. Instead of an inline onload attribute (which is blocked by nonce-based CSP), it emits a <link rel="preload"> plus a small <script nonce="..."> that promotes the preload to a full stylesheet once loaded. When nonce is empty the nonce attribute is omitted, which is fine only if the policy allows 'unsafe-inline'.
func GenerateCriticalCSSHelper ¶ added in v0.1.16
GenerateCriticalCSSHelper generates a Go helper function for templating. This can be used in your template files to inline critical CSS.
Types ¶
type BundleEntry ¶ added in v0.1.16
type BundleEntry struct {
// Name is the bundle identifier (e.g., "marketing", "dashboard").
Name string `yaml:"name" json:"name"`
// Input is the source CSS file.
Input string `yaml:"input" json:"input"`
// Output is the processed CSS file.
Output string `yaml:"output" json:"output"`
// Content paths for Tailwind to scan (globs).
Content []string `yaml:"content" json:"content"`
// CriticalCSS enables critical extraction for this bundle.
CriticalCSS *CriticalCSSConfig `yaml:"criticalCSS" json:"criticalCSS"`
}
BundleEntry defines a CSS bundle for code splitting.
type Config ¶
type Config struct {
// Input is the source CSS file (default: styles/main.css).
Input string `yaml:"input" json:"input"`
// Output is the processed CSS file (default: static/css/main.css).
Output string `yaml:"output" json:"output"`
// Watch enables watch mode for development.
Watch bool `yaml:"watch" json:"watch"`
// Minify enables CSS minification in production.
Minify bool `yaml:"minify" json:"minify"`
// SourceMap enables source map generation.
SourceMap bool `yaml:"sourceMap" json:"sourceMap"`
// Plugins configures which PostCSS plugins to enable.
Plugins PluginConfig `yaml:"plugins" json:"plugins"`
// CriticalCSS enables critical CSS extraction for above-the-fold content.
CriticalCSS CriticalCSSConfig `yaml:"criticalCSS" json:"criticalCSS"`
// Bundles defines multiple CSS entry points for code splitting.
Bundles []BundleEntry `yaml:"bundles" json:"bundles"`
// AllowOutputEscape allows writes outside the project directory.
AllowOutputEscape bool `yaml:"allowOutputEscape" json:"allowOutputEscape"`
}
Config holds PostCSS plugin configuration.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns the default PostCSS plugin configuration.
type CriticalCSSConfig ¶ added in v0.1.16
type CriticalCSSConfig struct {
// Enabled enables critical CSS extraction.
Enabled bool `yaml:"enabled" json:"enabled"`
// CriticalOutput is the path for critical CSS (inlined in HTML).
CriticalOutput string `yaml:"criticalOutput" json:"criticalOutput"`
// NonCriticalOutput is the path for non-critical CSS (async loaded).
NonCriticalOutput string `yaml:"nonCriticalOutput" json:"nonCriticalOutput"`
// Dimensions defines viewport sizes for critical CSS detection.
// Default: 1300x900 (desktop), 500x900 (mobile).
Dimensions []Dimension `yaml:"dimensions" json:"dimensions"`
// InlineMaxSize is the max size (in bytes) for inlining critical CSS.
// Default: 14KB (gzip) for single round-trip.
InlineMaxSize int `yaml:"inlineMaxSize" json:"inlineMaxSize"`
// CriticalContent lists template file paths/globs (e.g., "../routes/*.templ")
// whose classes are above-the-fold and should be prioritized in critical CSS.
// When empty, falls back to byte-size-only splitting.
CriticalContent []string `yaml:"criticalContent" json:"criticalContent"`
}
CriticalCSSConfig configures critical CSS extraction.
type Dimension ¶ added in v0.1.16
type Dimension struct {
Width int `yaml:"width" json:"width"`
Height int `yaml:"height" json:"height"`
Name string `yaml:"name" json:"name"`
}
Dimension defines a viewport size for critical CSS extraction.
type PluginConfig ¶
type PluginConfig struct {
// Typography enables @tailwindcss/typography (prose classes).
Typography bool `yaml:"typography" json:"typography"`
// Forms enables @tailwindcss/forms (form styling).
Forms bool `yaml:"forms" json:"forms"`
// AspectRatio enables @tailwindcss/aspect-ratio.
AspectRatio bool `yaml:"aspectRatio" json:"aspectRatio"`
// Autoprefixer enables autoprefixer for vendor prefixes.
Autoprefixer bool `yaml:"autoprefixer" json:"autoprefixer"`
// CSSNano enables cssnano for minification.
CSSNano bool `yaml:"cssnano" json:"cssnano"`
// PostCSSNested enables postcss-nested for nested CSS.
PostCSSNested bool `yaml:"postcssNested" json:"postcssNested"`
}
PluginConfig configures individual PostCSS plugins. Note: ContainerQueries and LineClamp are built into Tailwind v4.
type PostCSSPlugin ¶
type PostCSSPlugin struct {
// contains filtered or unexported fields
}
PostCSSPlugin provides PostCSS processing with Tailwind CSS v4 support.
func NewWithConfig ¶
func NewWithConfig(cfg *Config) *PostCSSPlugin
NewWithConfig creates a new PostCSS plugin with the given configuration.
func (*PostCSSPlugin) Commands ¶
func (p *PostCSSPlugin) Commands() []plugin.Command
Commands returns custom CLI commands.
func (*PostCSSPlugin) Dependencies ¶
func (p *PostCSSPlugin) Dependencies() []plugin.Dependency
Dependencies returns the required Bun packages for PostCSS.
func (*PostCSSPlugin) GetConfig ¶
func (p *PostCSSPlugin) GetConfig() *Config
GetConfig returns the current configuration.
func (*PostCSSPlugin) Init ¶
func (p *PostCSSPlugin) Init() error
Init initializes the PostCSS plugin.
func (*PostCSSPlugin) OnHook ¶
func (p *PostCSSPlugin) OnHook(hook plugin.Hook, ctx map[string]interface{}) error
OnHook handles lifecycle hooks.
func (*PostCSSPlugin) SetConfig ¶
func (p *PostCSSPlugin) SetConfig(cfg *Config)
SetConfig updates the configuration.
func (*PostCSSPlugin) Stop ¶
func (p *PostCSSPlugin) Stop()
Stop gracefully stops the PostCSS watcher.