Static Site (Certified Assets)
What This Is
The
recipe deploys a static site — a built frontend, docs, or any folder of files — to the
certified-assets canister on the Internet Computer, which serves it over HTTP with
response certification. The canister certifies
every response (certification v2 only, never the
escape hatch, no way to turn it off), and a
verifying HTTP gateway checks that proof before handing the response to the browser: visitors get content the canister provably committed to, not something altered in transit. Whether the proof is
checked depends on the gateway the visitor goes through:
https://<canister-id>.icp.net
verifies,
https://<canister-id>.raw.icp.net
does not (Pitfall 14).
This is the recommended way to host a frontend on the IC going forward. The recipe bundles a matched pair — the canister and its sync plugin — pinned together by one version. You point it at your build directory;
uploads, certifies, and serves.
The older
recipe (the SDK asset canister, configured with
) is still supported for existing projects but is no longer the recommended path. It is a
different canister with a different config format and API — see
references/legacy-asset-canister.md
. To move an existing project over, see
references/migrating-from-asset-canister.md
.
Prerequisites
- —
npm install -g @icp-sdk/icp-cli
. The recipe pins the canister + sync-plugin pair, both pre-built, so a plain // deploy needs nothing else.
- —
npm install -g @icp-sdk/ic-wasm
. A separate binary, not bundled with . This recipe shells out to it only when you set the field (the generated build guards on and fails with "ic-wasm not found"); other official recipes need it unconditionally, so installing both up front is the safe default — see the skill.
- Your frontend's build toolchain (e.g. Node.js >= 22 for a Vite/React app).
Canister IDs and URLs
Static-site canisters are created per-project — there is no global canister ID. After deployment the canister ID is stored in
.icp/<cache|data>/mappings/<environment>.ids.json
. Managed networks (the local replica) are
cache —
.icp/cache/mappings/local.ids.json
; connected networks (mainnet
) are
data —
.icp/data/mappings/ic.ids.json
.
| Environment | Browser URL |
|---|
| Local | http://<canister-name>.<environment>.localhost:8000
— the middle label is the environment name, by default, so http://frontend.local.localhost:8000
(this is the URL prints; http://<canister-id>.localhost:8000
also works — <canister-name>.localhost
with no environment label does not) |
| Mainnet | https://<canister-id>.icp.net
|
| Custom domain | (with DNS configuration) |
icp.yaml Configuration
yaml
canisters:
- name: frontend
recipe:
type: "@dfinity/static-site@v0.4.3"
configuration:
build:
- npm ci
- npm run build
dir: dist
Check the
static-site releases for the latest version and pin it in the
field. Because the recipe pins a matched canister + plugin pair, there is
no separate canister version to choose — the recipe version
is the canister version.
The recipe takes four configuration fields:
| Field | Required | Description |
|---|
| Yes | The single directory of built files to serve. The canister owns its whole URL space, so this is one directory, not a list. Vite → , Next.js export → . |
| No | Shell commands run before the canister exists to produce (e.g. ). No canister IDs are available yet. |
| No | Shell commands run at sync time, after the canister exists, with deployed canister IDs exported as env vars. Use this to bake a canister ID into a frontend build (see below). |
| No | // entries baked into the canister wasm via . is optional, or ; omitted means (ic-wasm's default), and only sections are readable by anyone via . Values are interpolated in a shell at build time, so works. |
Pitfalls
-
Using with the static-site recipe. is the
legacy asset canister's config file. The certified-assets canister does not read it — and because the plugin skips every dotfile and dot-directory (only
is exempt, Pitfall 12), a
in your
is not even uploaded. It is silently absent, so SPA fallback, headers, and security policy do nothing. Configure this canister with
and
instead (below).
-
Wrong SPA fallback rule. For client-side routing, the fallback is a
rewrite in
:
. The
status is what makes it a rewrite (serve the shell's contents at the requested URL, no visible redirect) so deep links work on fresh load and reload. Do
not use a
/
redirect, and do
not reach for
— that is a legacy asset-canister setting and has no effect here.
-
Relative asset paths in a SPA. Link assets with
absolute paths (
), never relative (
). Under a
rewrite, a relative URL resolves against the
client route: at
the browser requests
/dashboard/settings/assets/app.js
, which
answers with the HTML shell — producing a confusing MIME-type error instead of loading your script.
-
Expecting / to work. The certified-assets canister's upload API is
+
,
not the SDK asset canister's
/
/
.
from
@icp-sdk/canisters/assets
targets the
legacy canister and does
not work against static-site. Uploads happen through the recipe's sync plugin on
; there is no drop-in JS
equivalent for this canister. (If you need programmatic uploads, you are almost certainly on the legacy canister — see the legacy reference.)
-
/ in the wrong place. These two files must sit at the
root of your (e.g.
). They are read as configuration and never served as assets. Put them in your
(Vite) or
folder so the build copies them into
automatically — a file left at the project root but not copied into
is simply absent at deploy time.
-
Setting a reserved header in . The sync plugin
rejects these at deploy time with an explanatory error:
,
,
,
,
,
,
,
,
. To set an asset's media type use the bare
form (it routes to asset metadata, not a response header). To redirect, use
— a
header in
would not redirect (status stays
).
-
Assuming default security headers. Unlike the legacy canister's
security_policy: "standard"
, the certified-assets canister adds
no default headers — no
, no CSP, no
. If you want them, declare them in
(baseline below). The only headers it manages itself are the certification/serving ones and its
cookie.
-
A / rule pointing at a large file. An error-page target must be a
small, single-chunk file (under ~1.9 MB). Large files are served as certified
range responses that can't carry a 4xx status, so the plugin rejects such a rule at deploy time, naming it. (A
rewrite to a large file is fine.)
-
Expecting dynamic redirect captures. There is no
or
— you can't forward a captured segment (
). Every certifiable response must be enumerable ahead of time, so
/
support only exact paths, a trailing
subtree wildcard, and fixed destinations.
-
Switching an existing project from the legacy asset canister to static-site. Repointing
at
and running a plain
fails before anything is installed: these are two unrelated canisters with unrelated Candid interfaces, so icp-cli's pre-install check aborts with
Candid interface compatibility check failed: '<canister>' … You are making a BREAKING change
. Run
icp deploy --mode reinstall
instead. That replaces the wasm with the certified-assets canister,
discards the old stable memory — every legacy asset, permission, and
-derived setting is gone — and leaves the canister with empty state, after which the sync plugin uploads your whole
from scratch. Deploying static-site as a brand-new canister avoids the question entirely. Do
not silence the check with
: that pushes the in-place upgrade through onto stable memory certified-assets cannot read, leaving a live canister that serves nothing. See the migration reference.
-
Assuming a recipe version bump re-installs itself. Moving between certified-assets'
own releases is gentler than the legacy switch above — the Candid interface is stable across a release series, so nothing blocks the deploy — but a breaking bump still needs a reinstall
you run yourself. The canister and plugin are version-locked, so after bumping the recipe
upgrades in place and the sync plugin then refuses, reporting
assets canister version mismatch: canister is X, this plugin is Y
plus the fix:
icp canister install --mode upgrade
for a
patch bump (state preserved) or
icp canister install --mode reinstall
for a
breaking (pre-1.0 minor, post-1.0 major) bump, which wipes state so the next sync re-uploads every asset and redirect rule. (
→ is breaking: reinstall, then
.
→
is a patch: upgrade, then
.) A failed sync right after a version bump is expected — this, not a bug.
-
is uploaded automatically — no config needed. The plugin skips dotfiles and dot-directories
except , which it traverses normally. So
dir/.well-known/ic-domains
is served at
with no extra setting. (This is the opposite of the legacy canister, which needed an explicit
un-ignore rule.)
-
Access protection ordering. The recipe's
installs the canister
and syncs assets together, so a plain deploy-then-
briefly serves your content publicly. For a brand-new
private app, enable protection
before your real assets are synced — deploy a
containing only
,
, then deploy the full site — so assets are never world-readable. The login page must be
fully self-contained (inline CSS/JS,
URIs) — it is the only gate-exempt path, and any external subresource it references would itself be gated. See
Access protection.
-
Sharing or linking a URL. <canister-id>.raw.icp.net
serves the same site as
, but the gateway forwards responses
without checking the certificate, so the visitor gets no more assurance than from an ordinary web host. There is no canister setting to refuse
requests (unlike the legacy canister's
): the only clue is the unauthenticated
header, and which hostnames verify is a gateway deployment detail, not protocol. Link to
https://<canister-id>.icp.net
(or a custom domain on a verifying gateway) and treat
as a debugging tool only. With access protection on, a
URL is actively dangerous: the redirect and login page arrive unverified, so a non-verifying gateway could serve a fake login form and harvest tokens. The access cookie is host-only, so a session on the certified host does not carry over to
.
SPA Routing and Redirects:
Add a
file to the root of your
. Syntax follows
Netlify's — one rule per line, three whitespace-separated fields (
,
,
); blank lines and
comments are ignored.
# Single-page-app fallback: serve the shell for any unmatched path (a rewrite, status 200)
/* /index.html 200
# Permanent redirect to a new internal path
/old-blog /blog 301
# Redirect to an external site
/discord https://discord.gg/example 302
# Rewrite: serve /content/article.html at a pretty URL, no visible redirect
/article /content/article.html 200
# Subtree redirect: everything under /docs/v1/ moves to /docs/v2/
/docs/v1/* /docs/v2/ 301
# Custom error pages (target must be a small single-chunk file)
/secret /403.html 404
/retired-feature /sunset.html 410
Status codes:
/
/
/
redirect;
is a
rewrite;
/
serve an error page.
is always absolute and its only wildcard is a trailing
. Precedence, first match wins:
real files > automatic
clean-URL rules > your
(in file order) > the 404 fallback. Because a real file always wins, a
SPA rule only catches paths nothing else claimed.
SPA caveat — missing assets return HTML. With
, a typo'd
also matches
and serves the shell as
. To give real 404s under a build-output folder, scope a narrower rule
above the catch-all (rules match in file order):
/assets/* /404.html 404
/* /index.html 200
This needs a
in your
; declaring
means the built-in default 404 is not added.
Custom Headers:
Add a
file to the root of your
. Syntax follows
Netlify's : a path pattern on its own line, followed by indented
lines; a blank line or
ends a block. Patterns are absolute paths with an optional single
wildcard (which matches
too; there is no
or
).
A useful baseline — act like a senior security engineer and tighten the CSP for your app:
/*
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'
# Fingerprinted build assets never change — cache them hard
/assets/*
Cache-Control: public, max-age=31536000, immutable
# HTML should revalidate so deploys are picked up
/*.html
Cache-Control: public, max-age=0, must-revalidate
Key rules:
- Patterns match the file (asset key), not the visitor's URL. Write , not . For a SPA, a on (or ) is what every -rewritten client route gets; a block written against a route like matches no file and does nothing.
- All matching blocks contribute — a file matching several blocks gets every block's headers (same-name values are combined comma-separated; stays separate).
- is special — the bare form overrides the stored media type of the matching file (use it for extension-less files like ); it is single-valued, first-match-wins, and is not emitted as an ordinary header.
- is allowed, but don't use the name . The canister adds its own cookie to HTML responses as two headers with the same name and value: one , one
SameSite=None; Partitioned
(so it survives in a cross-site iframe). Seeing two headers is expected, not a duplicate-header bug.
- Reserved headers are rejected at deploy time — see Pitfall 6.
Clean URLs and the 404 Page
You don't link to
files — the canister maps each HTML file to a clean, extension-less canonical URL and
-redirects the other forms to it:
| Your file | Canonical URL | Also handled (→ ) |
|---|
| | |
| | , |
| | , |
Requesting the underlying
directly currently serves it
(a file always beats a routing rule). For a custom 404, put a
at the root of your
; otherwise a certified default is served. A SPA
rule takes over the whole path space, so it replaces the default 404 with your shell.
Custom Domains
To serve from your own domain, add a
file to your
, one domain per line:
example.com
www.example.com
is uploaded automatically (Pitfall 12), so the file is served where the IC boundary nodes look. Registering the domain itself (DNS records, ACME challenge, TLS provisioning) is a separate IC platform step — see the
skill.
Access Protection (private apps)
Put a login gate in front of an in-progress or preview app. Unauthenticated visitors get a certified
(HTML) or
(other assets). Configure it through controller-only canister methods:
sh
# 1. Add a self-contained /login.html to your dir and deploy.
icp deploy
# 2. Turn the gate on, naming your login page.
icp canister call frontend enable_protection '("/login.html")'
# 3. Mint a credential (here: a chosen passphrase valid ~1 year). Pass value = null for a random token.
# issue_token takes a record (IssueTokenArgs), not positional args.
icp canister call frontend issue_token '(record { label = "owner"; ttl_secs = 31536000 : nat32; value = opt "my-passphrase" })'
Ordering & the public window. The
recipe's
installs the canister and syncs your assets in one step, so the sequence above serves your content publicly for the brief window between that first deploy and
— fine when gating an existing or preview app. To avoid
any public exposure for a
brand-new private app, enable protection
before your real assets are synced: run the first
with a
containing only
, then
enable_protection '("/login.html")'
, then
again with the full site. The login page is gate-exempt, so nothing private is ever served unauthenticated (Pitfall 13). (Enabling on a truly empty canister also works — the canister reports
and self-heals to
once
is synced.)
| Method | Effect |
|---|
issue_token '(record { label = "<label>"; ttl_secs = <secs> : nat32; value = opt "<value>" })'
| Mints a token, returns its value. → high-entropy random token. |
revoke_token '("<label>")'
| Removes every token with that label, live. |
| Live tokens (controller-only). |
check_protection_status '()'
| , , or . |
| Gate off, drops all tokens. |
Always pass the argument explicitly —
for the methods that take none. Called with no argument,
opens an interactive prompt instead of sending an empty one.
This is
access gating, not confidentiality: node operators can read asset bytes and the token store, there is no rate-limiting, and it relies on the honest-replica/honest-gateway assumption. The gate runs canister-side on every hostname, but its redirect and login page are only verified through a verifying gateway, so never send people to a
URL of a protected app (Pitfall 14). Use high-entropy random tokens for share links; enable
before the first sync for a new private app (Pitfall 13). Full details in the
certified-assets access-protection docs.
Authorizing Uploaders
Uploads (sync) are performed by canister
controllers and by a separate set of
authorized syncer principals. To let a CI/deploy principal sync without giving it full canister control,
it — do
not , which grants upgrade/settings/delete power far beyond uploading.
bash
# Allow a principal to sync assets (upload), without making it a controller
icp canister call frontend authorize '(principal "<principal-id>")'
# List authorized syncers
icp canister call frontend list_authorized '()'
# Revoke
icp canister call frontend deauthorize '(principal "<principal-id>")'
Security Warning: icp canister settings update frontend --add-controller <principal-id>
grants full canister control (upgrade wasm, change settings, delete, drain cycles) — not just upload access. Prefer
for deploy pipelines.
Building Against Canister IDs ( vs )
runs before the canister exists, so it can't know any canister IDs. When a client-side app must bake in the ID of a canister it calls, build it in
— that runs at sync time, once IDs exist, and exports them:
yaml
canisters:
- name: frontend
recipe:
type: "@dfinity/static-site@v0.4.3"
configuration:
dir: dist
presync:
- npm ci
# $ICP_CLI_CID_BACKEND is the `backend` canister's principal.
- VITE_CANISTER_ID_BACKEND=$ICP_CLI_CID_BACKEND npm run build
Variables available to
:
(this canister),
(each project canister — name upper-cased, non-alphanumerics →
, e.g.
→
),
,
.
Alternatively, read canister IDs at
runtime in the browser from the
cookie the canister sets on every HTML response (works both locally and on mainnet with no environment branching) — see the
and
skills for the
pattern. Prefer the cookie over
.
What You Get Automatically
No configuration needed — on by default:
- Response certification — every response is certified; a verifying gateway (not ) checks the proof.
- Clean URLs — canonicalization (above).
- Compression — compressible assets are stored gzip + Brotli alongside the original and negotiated per request via . Compressible means: any ; any or suffix (so , ); , , , ; and except / (already compressed). An encoding is kept only if it actually came out smaller than the original.
- ETag / — content-hash ETag; unchanged files aren't re-downloaded.
- A default certified — replaceable with your own .
- The cookie — on HTML responses (as two headers, and ), carrying env vars (canister IDs) and the root key for the frontend.
Deploy & Verify
bash
# Start the local network
icp network start -d
# Build + deploy everything (or just the frontend)
icp deploy
icp deploy frontend
# Mainnet (needs cycles)
icp deploy -e ic frontend
Re-running
re-syncs: the plugin diffs your directory against the canister and uploads only what changed.
bash
# Canister is running
icp canister status frontend # Status: Running, non-zero memory
# Get the canister ID (there is no `icp canister id`; use status --id-only)
icp canister status frontend --id-only
# Fetch the index page (certified)
icp canister call frontend http_request '(record {
url = "/"; method = "GET"; body = vec {}; headers = vec {};
certificate_version = opt 2;
})' # → status_code = 200
# SPA fallback returns the shell, not 404
icp canister call frontend http_request '(record {
url = "/dashboard/settings"; method = "GET"; body = vec {}; headers = vec {};
certificate_version = opt 2;
})' # → 200 (index.html), NOT 404
# Open in a browser (this is the URL `icp deploy` prints)
# Local: http://frontend.local.localhost:8000
# Mainnet: https://<frontend-canister-id>.icp.net
Verifying Deployed Contents (state hash)
Certification proves responses match what the canister committed to; the
state hash proves
what it committed to matches a build reproduced from public source. The hash
prints (
canister reports state hash <hex>
) comes from the canister itself — a deploy self-consistency check,
not third-party verification. To verify a canister:
bash
# 1. Reproduce the build from source at the deployed version → ./dist (incl. _headers/_redirects)
# 2. Ask the canister its release, then build the verifier from THAT tag.
# Not published as a binary or on crates.io. --locked is required: Cargo.lock pins the
# compressor builds whose output bytes the hash covers; without it the hash differs.
icp canister call <canister-id> version '()' -n ic --query
# (record { major = 0 : nat32; minor = 4 : nat32; patch = 3 : nat32 })
cargo install --git https://github.com/dfinity/certified-assets --tag v0.4.3 --locked state-hash-cli
# 3. Compute the hash locally (prints 64 hex chars)
state-hash ./dist
# 4. Read the canister's hash (an update call, so consensus-backed); the hash is the last 32 bytes
icp canister call <canister-id> state_hash '()' -n ic -o hex | tail -c 65
- Target the canister by principal with ; resolves a canister name from a local project, which a third-party verifier doesn't have. Pass explicitly.
- 32 zero bytes is not a hash: the canister has never finished a sync, or one is in progress (a sync drops the cached hash when it starts). Re-read after the deploy completes.
- A mismatch means content, headers, or redirects differ from the source — or the canister was prepared with non-standard compressors (platforms embedding the crates may do this; the tool only reproduces what does).
- Not covered by the hash: the cookie (a controller can repoint a frontend's backend canister ID via env vars with a byte-identical build) and access protection (a matching hash says the canister holds your build, not that a visitor can reach it).
Legacy Asset Canister and Migration
- Maintaining an existing project (, uploads, roles, ): see
references/legacy-asset-canister.md
.
- Moving an existing asset-canister project to certified-assets / static-site: see
references/migrating-from-asset-canister.md
for the config mapping and the reinstall-mode caveat.
Additional References
- Load for the recipe system, structure, canister-ID injection, and the cookie / pattern.
- Load for DNS records, ACME challenge, and TLS provisioning of a custom domain.
- Load for reading the root key and canister IDs from in a frontend.
- Full upstream user docs: certified-assets docs.