cookie consent for Astro
@cookiecrumbs/astro inserts the tag as the first element of every page’s head, at build time for prerendered pages and per request in SSR. A middleware fills the server-side cookie reader.
the rule
Astro islands hydrate analytics the moment they mount. Without a consent layer the first paint of a content site already carries a tracker.
The rule is the same everywhere in the EU and the UK: nothing beyond what is strictly necessary may be stored on or read from a visitor’s device before they have agreed. That is Article 5(3) of the ePrivacy Directive, and the agreement has to meet the GDPR’s definition of consent: freely given, specific, informed and unambiguous, with a refusal that is as easy as the acceptance. The UK keeps the same rule in PECR, with narrow exemptions for low-risk statistics since 5 February 2026. California and the other US state laws work the other way round: no opt-in, but an opt-out link and support for the Global Privacy Control signal.
Three things follow for a website. Analytics, advertising and social scripts have to wait for a choice. The choice has to be recorded in a way you can show later, because Article 7(1) puts the burden of proof on you. And withdrawing has to be as easy as agreeing, which means a control that reopens the banner on every page. A banner that shows two buttons and loads Google Analytics anyway fails the first test, and that is the failure regulators have been fining, from the CNIL’s decisions against Google and SHEIN to the Dutch and Belgian authorities’ sweeps.
how it works
Astro sites are mostly static HTML with islands of interactivity, and that is good news for consent: the runtime can be written into the HTML at build time, first in the head of every page, with nothing to race against. The integration does exactly that for prerendered pages and repeats it per request for server-rendered ones, so a hybrid site behaves the same everywhere.
Islands are where trackers hide. A Partytown-loaded GTM, a client-only analytics island, a YouTube embed in a client:visible component: each of them either gets a category on its script tag or checks the consent state before mounting. The integration ships the shared components, and the middleware exposes the consent on Astro.locals so a page can decide server-side whether to render an embed or its placeholder.
Content sites tend to have hundreds of pages, and the scan crawls them in each consent state up to your plan’s budget. The result feeds the cookie declaration, which you can mount on your privacy page with CookieDeclaration and which updates itself when the next scan finds something new.
set-up
Five steps. The CLI does most of them, and every one is also a click in the dashboard.
Detects Astro, links the site, writes the config.
npx cookiecrumbs login
npx cookiecrumbs initOne line in astro.config.mjs. With auto: false you place <CookieCrumbs /> in your layout yourself.
npm i @cookiecrumbs/astro
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cookiecrumbs from '@cookiecrumbs/astro';
export default defineConfig({
integrations: [cookiecrumbs({ site: 'pk_live_…', env: 'production' })],
});Consent-bound tags get type="text/plain" and a category. Islands that load trackers can check the consent state before mounting.
<script type="text/plain" data-cc-category="analytics"
src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>The middleware sets the consent on locals, so a page can skip an embed entirely for visitors who said no.
// src/pages/index.astro
const { consent } = Astro.locals;
const showVideo = consent?.isGranted('marketing');The scan crawls the built site in each consent state. Sort once, publish.
npx cookiecrumbs scan --wait
npx cookiecrumbs push --env productionAstro sites often run GTM through Partytown in a web worker. The consent defaults still have to exist before it loads, which the integration guarantees by writing the runtime first.
Google Consent Mode v2 is the signalling layer between the banner and Google’s tags. Before any tag runs, seven signals (ad_storage, analytics_storage, ad_user_data, ad_personalization, functionality_storage, personalization_storage, security_storage) are set to denied for visitors in the EEA, the UK and Switzerland. The moment someone chooses, the runtime updates them and Google’s tags adjust. Since 15 June 2026, Google uses ad_storage as the controlling signal for Ads data, so getting the default right matters more than it used to.
CookieCrumbs sets the defaults synchronously, ahead of any tag manager, updates them on every decision, and ships a Google Tag Manager template so the consent triggers exist without hand-written listeners. In advanced mode, Google’s cookieless pings keep modelled conversions working for the visitors who said no. What it does not do is pretend to be a Google-certified CMP: for AdSense, Ad Manager or AdMob in the EEA you still need one with IAB TCF, and CookieCrumbs is not that today.
watch out
Each one shows up in the first scan as a tracker that fired before consent.
before you ship
Eight lines. The dashboard ticks the last two from real data.
type="text/plain" with a category, or the host is in the block map from the scan.what you get
Two domains, 100 subpages scanned a month per domain, every regulation, the CLI, the SDKs and the MCP server.
Every page, in each consent state, in a real browser. Cookies, pixels, iframes and storage keys, with the page and script that set them. Re-scanned on a schedule.
The cookie declaration writes itself from the result.
Tags stay inert until their category is granted. Reject all is as visible as Accept all. Seven layouts, 25 languages, Consent Mode v2, and the right rule per region.
21 kB, one file, no third-party requests of its own.
Each choice is stored with a timestamp, the banner version and a hash of the texts shown, chained to the record before it. Exports are signed. Hosted in Frankfurt.
Article 7(1), on the free plan.
free check
The homepage HTML, matched against the tracker database. No account, nothing stored. The full scan in the dashboard does the same for every page, in a real browser.
questions
next step
Add the site, run npx cookiecrumbs init in your Astro repo, and the consent log starts recording in the EU.