Hyvä Alpine Component

Overview

This skill provides guidance for writing CSP-compatible Alpine.js components in Hyvä themes. Alpine CSP is a specialized Alpine.js build that operates without the unsafe-eval CSP directive, which is required for PCI-DSS 4.0 compliance on payment-related pages (mandatory from April 1, 2025).

Key principle: CSP-compatible code functions in both standard and Alpine CSP builds. Write all Alpine code using CSP patterns for future-proofing.

CSP Constraints Summary

Component Structure Pattern

Every Alpine component in Hyvä follows this structure:

<div x-data="initComponentName">
    <!-- Template content -->
</div>
<script>
    function initComponentName() {
        return {
            // Properties
            propertyName: initialValue,

            // Lifecycle
            init() {
                // Called when component initializes
            },

            // Methods for state access
            isPropertyTrue() {
                return this.propertyName === true;
            },

            // Methods for mutations
            setPropertyValue() {
                this.propertyName = this.$event.target.value;
            }
        }
    }
    window.addEventListener('alpine:init', () => Alpine.data('initComponentName', initComponentName), {once: true})
</script>
<?php $hyvaCsp->registerInlineScript() ?>

Critical requirements:

1. Register constructor with Alpine.data() inside alpine:init event listener
2. Use {once: true} to prevent duplicate registrations
3. Call $hyvaCsp->registerInlineScript() after every <script> block
4. Use $escaper->escapeJs() for PHP values in JavaScript strings
5. Use $escaper->escapeHtmlAttr() for data attributes (not escapeJs)

Constructor Functions

Basic Registration

function initMyComponent() {
    return {
        open: false
    }
}
window.addEventListener('alpine:init', () => Alpine.data('initMyComponent', initMyComponent), {once: true})

Why named global functions? Constructor functions are declared as named functions in global scope (not inlined in the Alpine.data() callback) so they can be proxied and extended in other templates. This is an extensibility feature of Hyvä Themes - other modules or child themes can wrap or override these functions before they are registered with Alpine.

Composing Multiple Objects

When combining objects (e.g., with hyva.modal), use spread syntax inside the constructor:

function initMyModal() {
    return {
        ...hyva.modal.call(this),
        ...hyva.formValidation(this.$el),
        customProperty: '',
        customMethod() {
            // Custom logic
        }
    };
}

Use .call(this) to pass Alpine context to composed functions.

Property Access Patterns

Value Properties with Dot Notation

return {
    item: {
        is_visible: true,
        title: 'Product'
    }
}

<span x-show="item.is_visible" x-text="item.title"></span>

Transforming Values (Negation, Conditions)

CSP does not allow inline transformations. Create methods instead:

Wrong (CSP incompatible):

<span x-show="!item.deleted"></span>
<span x-text="item.title || item.value"></span>

Correct:

<span x-show="isItemNotDeleted"></span>
<span x-text="itemLabel"></span>

return {
    item: { deleted: false, title: '', value: '' },

    isItemNotDeleted() {
        return !this.item.deleted;
    },
    itemLabel() {
        return this.item.title || this.item.value;
    }
}

Negation Method Shorthand

For simple boolean negation, use bracket notation:

return {
    deleted: false,
    ['!deleted']() {
        return !this.deleted;
    }
}

<template x-if="!deleted">
    <div>The item is present</div>
</template>

Property Mutation Patterns

Extract Mutations to Methods

Wrong (CSP incompatible):

how to use hyva-alpine-component
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use hyva-alpine-component on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add hyva-alpine-component
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/hyva-themes/hyva-ai-tools --skill hyva-alpine-componentcopy
The skills CLI fetches hyva-alpine-component from GitHub repository hyva-themes/hyva-ai-tools and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/hyva-alpine-component
Reload or restart Cursor to activate hyva-alpine-component. Access the skill through slash commands (e.g., /hyva-alpine-component) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?