can How to Recipes include 3rd party astro:scope example?

[mrwormhole]

This is not really the problem of Astro but when there is a script that inserts some HTML element to DOM with specific scoped styles, it is not being applied. The best workaround was to use astro-scope, I can see that this is not the problem of Astro, as the scoped styles are generated via Vite and Vite doesn't know about DOM manipulated elements so it is missing scoped styles. But this really hurts the onboarding user experience of Astro people.

scope package
there should be How to guide on how to use this to ensure scoped style management in Astro docs.

Why? I have been experimenting with Astro and I have hit this block with this simple code and I was immediately thinking to go back where I come from [notably svelte] but then someone(in discord support) pointed out me to astro:scope package and I solved the issue but obviously this took some time from me while scanning the docs.

It would be a good idea to add a simplistic version of the problem below. Frankly there should be a giant warning in styles/DOM scripting docs to point out this possible issue. Like partials docs warn about users to not include CSS/JS in the partials.

example

<script>
    import scope from "astro:scope";
    import Cookies from "js-cookie";

    const hasSession = Cookies.get("session") !== undefined;
    const container = document.querySelector(".container");

    const dataAstro = `data-astro-cid-${scope}` // solves style scoping issue

    if (hasSession) {
        const loginLink = document.getElementById("login-link");
        if (loginLink) {
            loginLink.remove();
        }

        const profileHTML = `<a href="/profile"><button ${dataAstro}>View Profile</button></a>`;
        const logoutHTML = `<a href="#" id="logout-link"><button class="logout-btn" ${dataAstro}> Logout</button></a>`;

        if (container) {
            container.insertAdjacentHTML("beforeend", profileHTML);
            container.insertAdjacentHTML("beforeend", logoutHTML);
        }
    }
</script>

<div class="container my-custom-style">
    <h1>Welcome to Home Page</h1>
    <h3>This project is made by Astro &#x1F499;</h3>
    <a href="/login" id="login-link">
        <button>Go to Login page</button>
    </a>
</div>

<style>
    body {
    font-family: Arial, sans-serif;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    min-height: 100vh;
    margin: 0;
    background-color: #f5f5f5;
}
.container {
    text-align: center;
    background-color: white;
    padding: 2rem;
    border-radius: 8px;
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

button {
    background-color: #4285f4;
    color: white;
    border: none;
    padding: 12px 24px;
    border-radius: 4px;
    cursor: pointer;
    font-size: 16px;
    transition: background-color 0.2s;
    margin: 0.5rem 0;
    display: inline-block;
    width: 100%;
}
button:hover {
    background-color: #3367d6;
}
.logout-btn {
    background-color: #D32F2F;
    color: white;
    border: none;
    padding: 12px 24px;
    border-radius: 4px;
    cursor: pointer;
    font-size: 16px;
    transition: background-color 0.2s;
    margin: 0.5rem 0;
    display: inline-block;
    width: 100%;
}

.logout-btn:hover {
    background-color: #B71C1C; 
}
</style>

[sarah11918]

In general, I'm all for more recipes! 🚀

As you've noted, astro:scope is 3rd party, and we're hesitant to document too much relying on other projects. It's simply riskier because things could change without us knowing about it, and all of the sudden our docs are wrong (at best) or harmful (at worst) if there are e.g. security issues etc. with someone else's project. But since recipes are typically short and single-task focused, they're often easier to maintain and keep up to date.

I will also note that https://astro-tips.dev is also a place for additional content, as well as just writing a blog post or guide oneself! Some of our recipes come from content that individuals have written that we feel is general purpose enough to be helpful in docs, and then we ask if they'd like to contribute directly. And nothing stops anyone from writing a blog post!

As for mentioning within the styling documentation itself, while we do show an example of how a style tag compiles to a data-astro-cid-${scope} class with a brief mention, you're right that we don't point out very loudly that there will be some random string attached and that we provide no built-in way (other than inspecting your HTML output) to determine what that scope is and therefore manage it.

Do you think it would it be helpful to add an update to the end of that section of the docs something like....

Tip: Community CSS integrations such as astro-scope can help you manage your scoped styles."

OR, if you do write a recipe showing how to use astro-scope to obtain and make use of the hash in component logic, we also have a <RelatedRecipe /> component that we could instead stick there that would link to the specific recipe.

Do you think one of those solutions would have helped you get where you needed to go?

[mrwormhole]

I see, it might be a good idea to not do a recipe then, I agree when you have too many recipes, that could be outdated when versions change. I think lower recipe count is more elegant, I know projects who think recipes is like utility folder then they dump everything there and many things get outdated or abandoned then hard to pinpoint/clean.

I think

Tip: Community CSS integrations such as astro-scope can help you manage your scoped styles for dynamically added DOM elements

could clarify but if user doesn't know dynamically added DOM elements or vanilla scripting, it could be confusing as well

I feel like it should be mentioned over here(common script patterns) with a small sample perhaps what dynamically added DOM element means

If we mention this in Astro CSS docs, perhaps README.md of astro-scope should do the example to point out why it exists