Why Gatsby Sites Still Need Cookie Consent
Gatsby compiles your React components into static HTML at build time, producing pages that load quickly and score well on performance benchmarks. Speed alone does not grant a privacy exemption. If your Gatsby site sets _ga, _fbp, or any other non-essential cookie, you are subject to the same ePrivacy Directive and GDPR consent requirements as a server-rendered application.
Article 5(3) of the ePrivacy Directive requires prior consent before storing or accessing information on a user's device, with narrow exceptions for cookies that are strictly necessary. The European Commission formally withdrew the proposed ePrivacy Regulation in February 2025, meaning the existing Directive remains the controlling law for cookie consent across EU member states.
Static site generators sometimes create a false sense of security. Developers assume that because no server processes requests at runtime, fewer privacy obligations apply. That assumption is wrong.
Build Time vs Runtime: Where Cookies Actually Get Set
Gatsby's build process runs in Node.js. During gatsby build, there is no browser, no document object, and no cookies. Every cookie your Gatsby site sets is created at runtime - in the visitor's browser - after the static HTML has been served and JavaScript has hydrated.
This distinction matters for compliance. Third-party scripts injected through gatsby-ssr.js, gatsby-browser.js, or Gatsby plugins execute in the browser and can set cookies immediately on page load. If those scripts run before consent has been collected, you are in breach of Article 5(3).
The practical consequence: you must ensure that no non-essential script fires until the visitor has made a choice. That means either blocking scripts entirely until consent is recorded, or loading them conditionally based on consent state.
Common Cookies on Gatsby Sites
A typical Gatsby project with analytics and marketing integrations will set several cookies. The table below lists the most frequent ones and their cookie categories.
| Cookie | Set By | Category | Needs Consent? |
|---|---|---|---|
_ga | Google Analytics 4 | Analytics | Yes |
_ga_* | Google Analytics 4 | Analytics | Yes |
_fbp | Meta Pixel | Marketing | Yes |
_gcl_au | Google Ads | Marketing | Yes |
_hjSessionUser_* | Hotjar | Analytics | Yes |
__stripe_mid | Stripe | Functional | No (if essential to payment) |
gatsby-gdpr-* | gatsby-plugin-gdpr-cookies | Functional | No (stores consent state) |
Cookies that store consent preferences or maintain a shopping session are generally classified as strictly necessary and do not require consent. Everything else does.
How gatsby-ssr.js Works for Script Injection
Gatsby exposes several Server-Side Rendering APIs through the gatsby-ssr.js file. The most relevant for cookie consent is onRenderBody, which lets you inject elements into the <head> or <body> of every page during the build.
A cookie consent script placed here appears in the initial HTML served to every visitor. That is the correct behaviour - the consent banner must be present from the first paint, before any tracking scripts execute. If you instead inject a consent script through a React component or a layout file, it may only initialise after hydration, leaving a gap where other scripts can fire unchecked.
Pair gatsby-ssr.js with gatsby-browser.js for handling client-side route changes. Gatsby uses client-side navigation after the initial load, so your consent logic must persist across page transitions without re-initialising on every route change.
Adding a Cookie Banner to Gatsby
The recommended approach is to load your consent management script via gatsby-ssr.js using the setHeadComponents method. This places the script tag in the <head> of every generated page, guaranteeing it loads before any other non-essential scripts.
Script Placement Order
Order matters. Your cookie consent script must appear before Google Analytics, Meta Pixel, or any other conditionally loaded script. If the consent script loads after a tracking pixel, that pixel may fire a request and set cookies before the banner has rendered.
The Gatsby installation guide in the Kukie.io Help Centre walks through the exact code for gatsby-ssr.js. The snippet uses setHeadComponents to place the Kukie script as the first element in the document head.
Handling Gatsby Plugins That Set Cookies
Gatsby plugins like gatsby-plugin-google-gtag or gatsby-plugin-facebook-pixel inject their scripts during the build. These plugins typically do not wait for consent. You have two options: remove the plugin and load the script conditionally through your consent platform's auto-blocking feature, or use a consent-aware alternative such as gatsby-plugin-gdpr-cookies which checks for a consent cookie before initialising trackers.
Auto-blocking is the more reliable approach. It scans your page for known tracking scripts and prevents them from executing until the visitor accepts the relevant cookie category.
GDPR, CCPA, and Multi-Region Compliance
European visitors require opt-in consent under the GDPR and ePrivacy Directive. Californian visitors fall under the CCPA, which operates on an opt-out model. Canadian visitors are governed by PIPEDA, and Brazilian visitors by the LGPD.
A single consent banner with one set of rules will not satisfy all of these frameworks. Geo-detection determines a visitor's location and applies the correct consent model automatically. The Kukie.io geo-detection feature handles this by serving different banner behaviours based on the visitor's jurisdiction, so your Gatsby site can show an opt-in banner to EU visitors and an opt-out notice to US visitors from the same static build.
Testing Your Gatsby Cookie Banner
Deploying a banner is not enough. You need to verify that non-essential cookies are genuinely blocked before consent. Open Chrome DevTools, navigate to the Application tab, clear all cookies, and reload your Gatsby site. Before interacting with the banner, check the cookie list. Only strictly necessary cookies should appear.
Accept analytics cookies through the banner, then check again. The _ga and _ga_* cookies should now be present. Reject all categories and reload - no analytics or marketing cookies should persist.
Run a free cookie scan to get an automated report of every cookie your site sets, categorised and flagged for compliance issues. This catches cookies you may not be aware of, such as those set by embedded iframes or third-party fonts.
Common Mistakes with Gatsby Cookie Consent
Three errors appear repeatedly in Gatsby cookie implementations:
Loading the consent script via React Helmet or a layout component - this delays the script until after hydration, leaving a window for tracking cookies to fire.
Using gatsby-plugin-google-gtag without consent gating - the plugin injects the gtag script unconditionally. Without a blocking mechanism, GA4 cookies are set on every page load.
Forgetting client-side route transitions - Gatsby prefetches and renders pages client-side after the initial load. If your consent logic only runs on full page loads, scripts may fire on subsequent navigations without re-checking consent.
Each of these creates a gap where non-essential cookies reach the visitor's browser before valid consent has been collected.
Gatsby vs Other Static Site Generators
Gatsby is not the only SSG that requires careful consent handling. Next.js faces similar challenges with its Script component and SSR modes. Astro and Hugo generate fully static output but still serve client-side scripts that set cookies. The core principle is identical across all of them: no non-essential cookie may be set until the visitor has given informed, specific consent.
Frequently Asked Questions
Does a static Gatsby site need a cookie banner?
Yes. If your Gatsby site uses Google Analytics, Meta Pixel, Hotjar, or any other service that sets non-essential cookies, you need a cookie banner to collect consent before those cookies are placed.
Where should I place the cookie consent script in Gatsby?
Place it in gatsby-ssr.js using the setHeadComponents API. This ensures the script is present in the initial HTML before any tracking scripts execute.
Can gatsby-plugin-gdpr-cookies replace a full CMP?
It provides basic consent gating for specific services like Google Analytics and Facebook Pixel, but it does not offer geo-detection, automatic script blocking, consent logging, or multi-regulation support. A dedicated consent management platform covers those requirements.
Do I need consent for cookies that Gatsby sets during the build?
Gatsby does not set cookies at build time. All cookies are created at runtime in the visitor's browser. If those cookies are non-essential, they require consent under the ePrivacy Directive and GDPR.
How do I block Google Analytics on Gatsby before consent?
Remove gatsby-plugin-google-gtag and load the GA4 script conditionally through your CMP's auto-blocking feature, or use a consent-aware plugin that checks for a consent cookie before initialising the tracker.
Will a cookie banner slow down my Gatsby site?
A lightweight consent script adds minimal overhead. Loading it via gatsby-ssr.js ensures it is part of the initial HTML and does not require an extra network round-trip after hydration.
Take Control of Your Cookie Compliance
If you are not sure which cookies your Gatsby site sets, start with a free scan. Kukie.io detects, categorises, and helps you manage every cookie - so your visitors get a clear choice, and you stay on the right side of the law.
