Does Gatsby work in mainland China?
Yes — but "Gatsby" was never the thing that has to work in China. Gatsby only emits static files, and those can run from inside the mainland — which is exactly what pulls the project into the ICP filing regime.
In Gatsby's own words, "When you build your Gatsby application, the output is static content: HTML, CSS, JavaScript, images, etc.," and that content is "incredibly easy and affordable to host with any provider." The compliance question lives in those last two words: the moment "any provider" is a host inside the mainland, a mainland host's own rule applies — a domain "resolving to servers in the Chinese mainland" "must obtain an ICP filing before providing services" (State Council Order No. 292; MIIT Order No. 33). Serve the same build from offshore instead and every mainland visitor keeps crossing the filtered border; and if your pages carry a form, a comment box or analytics that captures a visitor's data, sending it out of the mainland is also a cross-border transfer under PIPL. The table below is Gatsby's own words, a mainland host's own rule, and the law each gate triggers.
This is a risk map, not a verdict — which gate bites first turns on where you host and what data your pages capture. Our China team can map your exposure with you →
What actually decides whether a Gatsby site is compliant in mainland China
| Fact | Primary source |
|---|---|
| Gatsby is a build tool, not a host — so there is nothing to "port" to China. In Gatsby's own words, "When you build your Gatsby application, the output is static content: HTML, CSS, JavaScript, images, etc.," and that content is "incredibly easy and affordable to host with any provider." Nothing in the build is bound to a foreign platform, so the identical files can be served from a host inside mainland China. "Does Gatsby work in China?" is really "which host do you deploy the build to?" — and that is where compliance begins. | Gatsby — Deploying and Hosting (v2.gatsbyjs.com docs), retrieved 2026-10-07 |
| Hosting the build inside the mainland is the act that triggers the ICP filing. A mainland host states the rule plainly: services "with domain names resolving to servers in the Chinese mainland" "must obtain an ICP filing before providing services," and "ICP filing applies only to servers located in the Chinese mainland." That is the ICP filing regime (备案) under State Council Order No. 292 and MIIT Order No. 33 — a filing that binds to a licensed mainland hosting resource and a mainland legal entity, which a foreign company cannot hold in its own name. | Alibaba Cloud — What is an ICP filing? (alibabacloud.com), retrieved 2026-10-07; State Council Order No. 292; MIIT Order No. 33 |
| No filing, no service — even once the files are physically in-country. For a domain pointing at a mainland server without a filing, the same host warns that "the Alibaba Cloud monitoring system blocks access to the domain name and prompts you to complete the filing process." That is the interlock to plan around: moving delivery inside the mainland removes the border crossing and, in the very same move, makes the filing non-optional — the speed you gain and the filing you incur are one decision. | Alibaba Cloud — What is an ICP filing? (alibabacloud.com), retrieved 2026-10-07 |
| A static site is light on personal data — until a page starts collecting it. A brochure-style Gatsby build that captures nothing keeps PIPL exposure small, and that is the honest reason ICP and in-country delivery — not data-transfer law — are usually the dominant gate here. But add a contact form, a comment box or an analytics beacon that captures a mainland visitor's personal information (their real IP address included) and sends it to an offshore endpoint, and that is a cross-border transfer of personal information PIPL governs (Chapter III, Articles 38–43: notice, separate consent, and one permitted transfer mechanism). PIPL exposure rises with whatever your pages actually collect. | PIPL Chapter III, Articles 38–43 |
Sources verified by the 21YunBox compliance team on 2026-10-07.
Deploying a Gatsby site is the part teams worry about least once they have done it once: Gatsby compiles your project to static files, and static files go almost anywhere. What actually decides whether that site can serve mainland China is not the build command — it is where you point the deploy. The instant those files are served from inside the mainland, two gates open at the same time, and they are the real work. This guide keeps the practical steps, but anchors them to the question that outlasts any deploy config: is the site licensed to operate in China, and is it delivered from inside it?
Here is the honest starting point, and it is good news for a change. Gatsby is a static-site generator, not a hosted platform — there is no “Gatsby region” to lack and no account to migrate. The build output is ordinary static content, and that is precisely why a Gatsby site can run from infrastructure inside mainland China in a way a hosted-only service cannot. What follows from that freedom is responsibility: an ICP filing on the mainland host, in-country delivery to remove the border crossing, and a PIPL check on anything your pages collect. Below is Gatsby’s own description of its output, a mainland host’s own filing rule, and the law each gate triggers, so you can take it to counsel.
Gatsby in China at a glance
| What decides it | In their own terms — and China's own law |
|---|---|
| What Gatsby is | A static-site generator, not a host. In Gatsby's words the build output is “static content: HTML, CSS, JavaScript, images, etc.,” and is “incredibly easy and affordable to host with any provider.” There is no platform to leave and no mainland region to lack — the same build can run in-country. |
| Gate 1 — in-country delivery | Serve that build from offshore and every mainland request crosses a congested, filtered border. Hosting it inside the mainland removes the crossing. That is the performance half of the question — and on its own it does not stay alone for long. |
| Gate 2 — the ICP filing | A domain “resolving to servers in the Chinese mainland” “must obtain an ICP filing before providing services” (State Council Order No. 292; MIIT Order No. 33). The filing binds to the licensed mainland host and to a mainland legal entity. |
| Why they are one decision | In-country delivery is the same act that triggers the filing — so the speed decision and the licensing decision are a single decision, not two. You cannot host inside the mainland for speed and stay outside the filing regime. |
| Visitor data (PIPL) | A pure static page collects little. Add a form, comment box or analytics that captures a visitor's data and sends it offshore, and PIPL's cross-border rules apply (Articles 38–43). Exposure scales with what the pages actually collect. |
| The working design | Keep building with Gatsby; add ICP-filed, in-country delivery in front of your origin. An overlay, not a migration — no rebuild, no second codebase. |
What “deploying Gatsby” actually is
Every Gatsby deployment reduces to one command and one folder. Running gatsby build compiles your project — in Gatsby’s own words, “the output is static content: HTML, CSS, JavaScript, images, etc.” — into a public/ directory, and deploying is nothing more than serving the contents of that folder from a web host. A typical static-site configuration looks the same wherever it runs:
| Setting | Value |
|---|---|
| Build command | gatsby build (or yarn && yarn build) |
| Publish directory | public/ |
| Build output | Static HTML, CSS, JavaScript and images — servable by any host |
Because none of that is tied to a particular platform, the one decision the command line never asks you is the one that matters most: which host serves public/. Point it at an offshore host and you have a global site that merely happens to be reachable from China across the border. Point it at a host inside the mainland and you have an in-country site — and, in the same stroke, an ICP obligation. That single choice, not the framework, is what this article is really about.
Gate 1: delivery from inside the mainland
A Gatsby build served from outside mainland China is not broken; it is simply on the far side of a border that is congested and filtered. The symptom teams report is rarely a clean failure — it is inconsistency. The same page is quick in the morning and unreliable by the evening, and the assets your build pulls in (a web font, an embedded video, a third-party script) each fail on their own schedule. A content-delivery layer only helps here if its points of presence are genuinely inside the mainland; Hong Kong and Singapore feel close on a map and sit on the wrong side of the crossing. Delivering the build from inside mainland China is what removes the border round trip. That is gate 1, and taken alone it is a performance question — but it does not stay alone, because the act that fixes it also opens the next gate.
Gate 2: the ICP filing the host now needs
The instant your public/ folder is served from a server inside the mainland, a licensing duty attaches to that host. A mainland provider states it without ambiguity: a domain “resolving to servers in the Chinese mainland” “must obtain an ICP filing before providing services,” and a domain without one is blocked at the network until the filing is completed. The ICP filing (备案), under State Council Order No. 292 and MIIT Order No. 33, binds to the licensed mainland hosting resource and to a mainland legal entity — which is why a foreign company usually cannot file in its own name, and why “we will just put the files on a Chinese server” turns out to be a company-structure task as much as a technical one. For the mechanics, see what the China ICP license is and how you get one.
This is the part worth internalizing before you choose a host: the move that fixes gate 1 is the move that opens gate 2. In-country delivery removes the border crossing and, in the identical step, makes the filing mandatory. There is no setup that buys you in-country delivery while keeping you clear of the filing — the speed and the license are acquired in the same transaction, or not at all.
The PIPL question — only as big as what your pages collect
This is where a static site genuinely differs from a data-heavy application, and it is worth being honest about rather than inflating. A brochure-style Gatsby build that collects nothing carries little personal-data exposure, so for many static sites the ICP filing and in-country delivery are the whole of the compliance story. The picture changes the moment a page starts capturing data about mainland visitors. A contact form, a newsletter sign-up, a comment widget, an analytics beacon — each can collect personal information, and a visitor’s real IP address counts as personal information in its own right. Sending any of that to an endpoint outside the mainland is a cross-border transfer of personal information that PIPL governs (Articles 38–43: notice, separate consent, and one permitted transfer mechanism). The honest rule of thumb is to let your PIPL effort scale with what your Gatsby pages actually collect, while keeping the ICP filing and in-country delivery as the baseline either way.
This is a risk map for planning, not a legal verdict: which gate binds first, and how far PIPL reaches, turn on your entity, your host and the data your pages capture — all worth settling with counsel before launch.
Where 21YunBox fits — a compliant overlay, not a migration
You keep building and shipping with Gatsby exactly as you do today — the same gatsby build, the same public/ output, the same workflow. What 21YunBox adds is the single piece a build tool structurally cannot supply on its own: ICP-filed delivery from inside the mainland, placed in front of your existing origin — no rebuild, no second codebase, and no move off the stack you already run. Your Gatsby build stays the source of truth; our China team maps which obligations apply to your entity and to the data your pages collect, handles the ICP filing on the in-country hosting resource, and stands up the compliant in-country delivery that serves your mainland audience. The framework was never the hard part — the license to operate, and the delivery that license permits, are, and that is exactly the half we hold.
Related reading:
