Deploy frontend assets to the IC. Covers certified assets, SPA routing with .ic-assets.json5, custom domains, content encoding, and programmatic uploads. Use when hosting a frontend, deploying static files, configuring custom domains, or setting up SPA routing on IC. Do NOT use for canister-level code patterns.
The asset canister hosts static files (HTML, CSS, JS, images) directly on the Internet Computer. This is how web frontends are deployed on-chain. Responses are certified by the subnet, and HTTP gateways automatically verify integrity, i.e. that content was served by the blockchain. The content can also be verified in the browser -- not a centralized server.
@icp-sdk/canisters (>= 3.5.0), @icp-sdk/core (>= 5.0.0) — for programmatic uploadsAsset canisters are created per-project. There is no single global canister ID. After deployment, your canister ID is stored in .icp/data/mappings/ (per environment).
Access patterns:
| Environment | URL Pattern |
|---|
| Local | http://<canister-id>.localhost:8000 |
| Mainnet | https://<canister-id>.ic0.app or https://<canister-id>.icp0.io |
| Custom domain | https://yourdomain.com (with DNS configuration) |
Wrong dir path in icp.yaml. The configuration.dir field must point to the directory containing your build output. If you use Vite, that is dist. If you use Next.js export, it is out. If the path does not exist at deploy time, icp deploy fails silently or deploys an empty canister.
Missing .ic-assets.json5 for single-page apps. Without a rewrite rule, refreshing on /about returns a 404 because the asset canister looks for a file literally named /about. You must configure a fallback to index.html.
Missing or misconfigured build in the recipe. If configuration.build is specified, icp deploy runs those commands automatically before uploading the dir contents. If build is omitted, you must run your build command (e.g., npm run build) manually before deploying — otherwise the dir directory will be stale or empty.
Not setting content-type headers. The asset canister infers content types from file extensions. If you upload files programmatically without setting the content type, browsers may not render them correctly.
Deploying to the wrong canister name. If icp.yaml has "frontend" but you run icp deploy assets, it creates a new canister instead of updating the existing one.
Exceeding canister storage limits. The asset canister uses stable memory, which can hold well over 4GB. However, individual assets are limited by the 2MB ingress message size (the asset manager in @icp-sdk/canisters handles chunking automatically for uploads >1.9MB). The practical concern is total cycle cost for storage -- large media files (videos, datasets) become expensive. Use a dedicated storage solution for large files.
Pinning the asset canister Wasm version below 0.30.2. The ic_env cookie (used by safeGetCanisterEnv() from @icp-sdk/core to read canister IDs and the root key at runtime) is only served by asset canister Wasm versions >= 0.30.2. The Wasm version is set via configuration.version in the recipe, independently of the recipe version itself. If you pin an older Wasm version, the cookie is silently missing and frontend code relying on ic_env will fail. Either omit configuration.version (latest is used) or pin to 0.30.2 or later.
Not configuring allow_raw_access correctly. The asset canister has two serving modes: certified (via ic0.app / icp0.io, where HTTP gateways verify response integrity) and raw (via raw.ic0.app / raw.icp0.io, where no verification occurs). By default, allow_raw_access is true, meaning assets are also available on the raw domain. On the raw domain, boundary nodes or a network-level attacker can tamper with response content undetected. Set "allow_raw_access": false in .ic-assets.json5 for any sensitive assets. Only enable raw access when strictly needed.