Does npm Work in China? Data Residency, ICP & Cross-Border Rules
Your private, scoped npm packages are proprietary source code that often embeds credentials and tokens, and on npm's hosted registry they sit offshore — a data-residency and PIPL cross-border question, not a reachability one. Self-hosting a private npm registry in-country keeps those private packages and secrets resident.
Does npm work in China?
Whether npm “works” in China is the wrong question — your private, scoped npm packages are your proprietary source code, and on npm's hosted registry they live offshore. That, not whether a build can resolve packages from Shanghai, is what decides whether the setup is defensible.
In npm's own words, “With npm private packages, you can use the npm registry to host code that is only visible to you and chosen collaborators.” The npm registry is npm's hosted service, run offshore — so your private packages, and the credentials, tokens and config they routinely embed, sit outside the mainland, and your China build's dependency supply chain resolves across the border. Held abroad, any personal data or secrets in those packages is a cross-border transfer PIPL governs, and for a CIIO or large-volume handler the data-localization duty (Article 39 (formerly Article 37)) points the other way. A self-hosted private registry — Verdaccio, or Nexus / Artifactory in your own infrastructure — keeps those private packages and secrets resident in-country.
This is a risk picture, not a verdict — your obligations turn on what your private packages carry and who your contributors are. Our China team can map your npm residency and supply-chain exposure with you →
What npm's own documentation says about China
| Fact | Primary source |
|---|---|
| In npm's own words: “With npm private packages, you can use the npm registry to host code that is only visible to you and chosen collaborators.” Those private, scoped packages are your proprietary source code — trade secrets — and routinely embed build credentials, API tokens and config. On npm's hosted registry they live offshore; npm publishes no mainland-China region (confirm current with npm). A build resolving them is not the same as that code being resident. | npm Docs — About private packages, retrieved 2026-10-13 |
| A genuine in-country path exists: a self-hosted private npm registry you run on your own infrastructure. Verdaccio documents itself as “a private npm registry” where “all packages that you publish are private and only accessible based in your configuration”; Sonatype Nexus and JFrog Artifactory offer the same self-managed model. Run it inside the mainland and your private packages, build artifacts and embedded secrets stay resident, with your China build's supply chain kept in-country. | Verdaccio Docs — What is Verdaccio?, retrieved 2026-10-13 |
| For a critical information infrastructure operator or a large-volume handler, personal information and important data collected and generated in China must be stored inside the mainland, with a security assessment before any export — the Cybersecurity Law data-localization rule, Article 39 (formerly Article 37) as renumbered by the 2025 amendment in force 2026-01-01. Private packages and build artifacts held on an offshore registry have no mainland footing to satisfy that. | PRC Cybersecurity Law, Article 39 (formerly Article 37); 2025 amendment in force 2026-01-01 |
| Contributor identities, access logs, embedded secrets and any personal data inside private packages or build metadata, held on an offshore registry, are a PIPL cross-border transfer (Articles 38–40): the handler must give notice, obtain separate consent, and clear one mechanism — a CAC security assessment, the CAC standard contract, or certification. | PRC Personal Information Protection Law, Articles 38–40; CAC cross-border rules (March 2024) |
Sources verified by the 21YunBox compliance team on 2026-10-13.
For a mainland-China operation, the deciding question about npm is not whether a build in Shanghai can resolve a public package — it is where your private packages live, what they carry, and on what legal basis they got there. Pulling open-source dependencies is a reachability topic, and not the one that decides whether your setup is defensible. Your private, scoped npm packages are different: they are your proprietary source code — trade secrets — and they routinely embed build credentials, API tokens and configuration, with the occasional fixture of personal data riding along. Published to npm’s hosted registry, that concentrated intellectual property sits offshore, and your China build’s dependency supply chain — what code, with what provenance and integrity, enters your China deployment — resolves across the border. Residency and cross-border transfer, not load time, are what decide this.
Does npm work in China? At a glance
| What decides it | What it means for mainland China |
|---|---|
| What your private packages hold | Your private, scoped packages are proprietary source code — trade secrets — and routinely embed build credentials, API tokens and configuration, plus any contributor metadata and fixture data in the pipeline. |
| Where the registry runs | Published to npm, private packages live on npm's hosted registry (npmjs.com), which runs on offshore infrastructure. npm publishes no mainland-China region (confirm current with npm). |
| Data residency | For a CIIO or large-volume handler, personal information and important data collected in China must be stored in the mainland (Cybersecurity Law Article 39 (formerly Article 37)) — a duty an offshore registry cannot meet. |
| Cross-border transfer | Contributor identities, access logs and any personal data inside private packages or build metadata, held offshore, are a PIPL cross-border transfer (Articles 38–40): notice, a separate consent, and one transfer mechanism. |
| Your build's supply chain | A China build that resolves from an offshore registry runs its dependency supply chain across the border. A registry mirror or cache speeds resolution — it does not move your private packages or secrets in-country. |
| The residency lever | A self-hosted private registry (Verdaccio, or Nexus / Artifactory in your own infrastructure) run inside the mainland keeps the private packages, build artifacts and embedded secrets resident. |
Door one — your private packages are proprietary code, and residency follows where they’re hosted
Start with what the registry holds, because that is what China’s law answers to. The public npm registry pulls community dependencies, but that is not the part that decides this. Your private, scoped packages are the authoritative store of code you do not publish to the world: proprietary libraries, internal SDKs and build tooling — a concentrated slice of your intellectual property — which routinely carry baked-in credentials, API tokens, registry auth and configuration, and sometimes personal data in test fixtures. In npm’s own words, “With npm private packages, you can use the npm registry to host code that is only visible to you and chosen collaborators.”
That hosting is the point. The npm registry is npm’s hosted service, running on offshore infrastructure, and npm publishes no mainland-China region (something to confirm with npm directly rather than assume). If you are a critical information infrastructure operator, or you handle personal information at volume, personal information and important data collected and generated in China must be stored in the mainland, with a security assessment before any export — the Cybersecurity Law data-localization rule, Article 39 (formerly Article 37) as renumbered by the 2025 amendment in force 2026-01-01. An offshore registry holding your proprietary packages and embedded secrets has no mainland footing to satisfy that.
Door two — contributor identities, secrets and supply-chain provenance
The second door is PIPL and the integrity of what enters your China build. Private packages and the pipeline around them carry more than code: usernames and email addresses of who published, built and promoted a release, access logs, and any personal data that finds its way into package contents or build metadata. Under the Personal Information Protection Law, holding that data on infrastructure outside the mainland is a cross-border transfer (Articles 38–40): the handler must give notice, obtain a separate consent for the transfer, and clear one mechanism — a CAC security assessment, the CAC standard contract, or certification. Minimizing the secrets and personal data that enter package contents in the first place is part of the fix, but it does not move the store on its own. And because your China build resolves its dependencies from wherever the registry runs, the provenance and integrity of the code entering your China deployment are governed across the border too — a software-supply-chain exposure a connectivity check never surfaces.
Why a reachability check misses this
A “can my build resolve packages from Shanghai” test answers the wrong question. A registry mirror or cache, or connectivity tuning, changes how fast and how reliably a dependency resolves — it does not change where your private packages, their embedded secrets and the build provenance actually live. So a setup can look perfectly healthy from inside China while every private package, every token baked into it, and every contributor record still sits offshore. The residency and cross-border questions above are invisible to a reachability probe precisely because the packages keep resolving — which is why the move that matters is moving the private store in-country, not making the offshore store merely reachable or mirrored. We publish no first-party measurement of npm connectivity from inside China, so we put no figures here; it is something we would measure against your actual setup rather than assert.
This is a risk map, not a verdict: whether you need in-country storage, a transfer mechanism, a reworked consent flow, an ICP filing for any public-facing developer portal, or some combination depends on what your private packages carry, how much, and who your contributors are — worth settling with counsel before you build.
The lever — map, localize, deliver
Because a genuine self-hosted private registry exists for npm, there is a real in-country path, and 21YunBox never uses or suggests circumvention of any kind.
- Map — inventory which of your packages are private (your proprietary code), whether they embed credentials, tokens or configuration, where that private registry is hosted today, the residency basis, and how your China build’s dependency supply chain crosses the border.
- Localize / govern — run the private registry and artifact store in-country (self-hosted — Verdaccio, or Nexus / Artifactory in your own infrastructure), so the proprietary code and embedded secrets stay resident; keep your China build’s supply chain in-country; and minimize what crosses the border.
- Deliver — put a compliant, in-country private registry and artifact delivery in front of (or in place of) the offshore service; 21YunBox stands up the in-country layer without a rebuild.
Making the public registry merely reachable or mirrored is not the answer — your private packages and secrets are still offshore, and resolving them faster does not change that. Keeping the private registry and artifacts in-country is.
Where 21YunBox fits — a compliant overlay, not a migration
You keep using npm. We add the piece an offshore registry cannot provide on its own: a lawful, in-country home for a self-hosted private registry, so your proprietary packages, build artifacts and embedded secrets stay resident where the law requires, with compliant ICP-filed delivery for the developer access and any public-facing portal in front of it — placed around your existing setup, with no rebuild, no second codebase, and no migration off npm. As a partner to the toolchain you already run, our China team maps your PIPL cross-border, consent and data-residency obligations against your entity and your pipeline, then stands up the in-country registry and delivery a defensible China presence needs. We never use or suggest circumvention of any kind.
Related reading:
- Cross-border data transfers under PIPL
- China’s Cybersecurity Law and data localization
- How to get an ICP filing for China
