scripts

Inject third-party scripts into the document head or body via the Rango Script handle.

Updated Nov 7, 2025
One-click install
npx skills add https://github.com/rangojs/rango --skill scripts-rangojs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: scripts
Source: https://github.com/rangojs/rango/tree/main/packages/rangojs-router/skills/scripts
Command: npx skills add https://github.com/rangojs/rango --skill scripts-rangojs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @rangojs/router.

What problem does it solve? Adding third-party scripts like Google Tag Manager, analytics snippets, or widget loaders to a React Server Components app is error-prone: scripts can silently fail on soft navigations, violate CSP nonce policies, or load in the wrong order. This Skill shows how to push script configs from server handlers and render them correctly with the built-in <Scripts /> component. ## Core Features & Use Cases - Three typed script shapes: Inline (raw JS body), external async (React resource, deduped by src), and external ordered (defer/plain), enforced as a discriminated union so invalid combinations are compile errors. - Automatic CSP nonce handling: Document-rendered scripts carry the request nonce automatically, with guidance on 'strict-dynamic' policies for soft-navigation async scripts. - Honest execution contract: Explains which scripts run on hard loads versus soft <Link> navigations, and how the frozen inline/ordered set prevents silently dead scripts. - Use Case: Add Google Tag Manager to a Rango app by pushing an inline self-injecting bootstrap from the root layout, then fire per-navigation page_view events from a "use client" component. ## Quick Start Add Google Tag Manager to my Rango app by pushing a script config from the root layout and rendering it with the Scripts component in the Document.

Frequently Asked Questions about scripts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add Google Tag Manager to a React Server Components app?

Push an inline script config with ctx.use(Script) containing a self-injecting GTM bootstrap from your root layout handler, then render it with the <Scripts /> component in your Document. Use a "use client" component to fire page_view events on subsequent soft navigations.

How to inject third-party scripts in the Rango router?

Call ctx.use(Script)(config) from a server handler or loader with one of three shapes: inline children, external async src, or external ordered src with optional defer. Render them in your Document with <Scripts /> for head scripts and <Scripts position="body" /> for body scripts.

Why does my script not run on client-side navigation in React?

React mounts client-side scripts via innerHTML, which the HTML spec never executes, so inline and ordered scripts are document-load only. Only external async scripts load on soft navigations because React treats them as deduped resources.

Does the Rango Script handle support CSP nonces?

Yes, document-rendered scripts automatically carry the per-request CSP nonce with no manual wiring. Async scripts first encountered on soft navigation lack a nonce but still load under a 'strict-dynamic' script-src policy via React's nonced runtime.

Can I use onLoad or onError callbacks with pushed script configs?

No, callbacks cannot cross the server handle boundary because configs are serialized to the client, so all on* handlers are excluded. Render your own "use client" component with a load listener keyed off the script id instead.