Astro docs: Scripts and event handling
A <script> in a .razor component is bundled by Astro, the same way one in an .astro file
is: TypeScript compiles, npm and relative imports resolve, the output is hashed and emitted once per
page however many times the component renders.
<button class="go">Go</button>
<script>
import { track } from '../lib/analytics';
for (const button of document.querySelectorAll('.go')) {
button.addEventListener('click', () => track('go'));
}
</script><button class="go">Go</button>
<script>
import { track } from '../lib/analytics';
for (const button of document.querySelectorAll('.go')) {
button.addEventListener('click', () => track('go'));
}
</script>Identical, and it goes through the same pipeline. is:inline opts out, exactly as in Astro: the
block stays where it was written, unprocessed and undeduplicated.
The block is read out of the Razor compiler's own output at build time. That is what makes it safe:
Razor compiles a static block into a string literal and an interpolated one into an element built
piece by piece, so "can this be taken?" is a structural question the compiler has already answered,
not a guess. The same distinction decides whether a <style> can be lifted.
It is then declared as one of the page's own scripts rather than imported. That difference is the whole design. A stylesheet can be a real import of the generated component module, because CSS is collected from the module graph whether or not the importer is client-side. A script cannot: the generated module is server-only — a C# component never hydrates — so a script imported from it would be bundled into the server and never reach the browser. Declaring it instead puts it where Astro's own page scripts are, and Astro emits it for the browser from there.
There is no define:vars, so data goes through the DOM — which is what Astro recommends anyway for
anything beyond a constant:
@code {
[Parameter] public string Label { get; set; } = "";
}
<button class="go" data-label="@Label">@Label</button>
<script>
for (const button of document.querySelectorAll('.go')) {
button.addEventListener('click', () => console.log(button.dataset.label));
}
</script>A <script> that interpolates is not bundled. Razor compiles
<script>console.log("@Label");</script>into an element it builds piece by piece rather than into a literal, so its text does not exist until
the component renders — and what Astro bundled would be the source rather than what runs. It falls
back to being emitted as written, and the build says so rather than leaving you to notice. Use a
data- attribute, as above.
This is Astro's limit too, not one AstroSharp adds. define:vars is how an .astro file passes
per-render values into a script, and Astro's own answer is to stop bundling it: the directive implies
is:inline, and the renderer un-hoists the block and prepends const x = … to it. A script carrying
values that change per render cannot be one shared hashed chunk in either language. The fallback here
lands in the same place.
define:vars itself is .astro-only — the directive is compiler syntax. The data- attribute
above is the equivalent, and is what Astro recommends for anything beyond a constant. For a
<style>, Astro.Vars is the direct equivalent and does keep the block bundled.
<script src="..."> is left as written. Astro turns one into an import of the source; that is a
different shape from an inline block and is not handled yet.
Astro's client-side modules belong here too. astro:prefetch's prefetch() and
astro:transitions/client's navigate() are browser JavaScript, so they are imported inside a
<script> and resolve there exactly as they would in an .astro file. Neither has, or needs, a C#
wrapper — nothing on the server can call them.
A <script> is not a component lifecycle. It is ordinary browser JavaScript operating on the
HTML C# rendered. Making the component itself interactive is
client rendering, which is a different feature with a different cost.
A C# component emits its script tag where it stands, not in the document head, because a
component used inside an .astro page has no way to reach that page's head. A module script is
deferred wherever it sits, so this is a difference in markup rather than in behaviour.