|
| 1 | +# Static Site Recipe |
| 2 | + |
| 3 | +Deploy a static frontend to the [`dfinity/certified-assets`](https://github.com/dfinity/certified-assets) canister, with response certification and asset synchronization handled for you. |
| 4 | + |
| 5 | +Each released version of this recipe pins a **matched pair** of the certified-assets canister wasm and its sync plugin. The two must share the same version, so — unlike a generic pre-built recipe — there is no user-selectable canister `version`; choose it via the recipe version in the `type` field instead. |
| 6 | + |
| 7 | +## Usage |
| 8 | + |
| 9 | +Reference this recipe in an `icp.yaml` (or `canister.yaml`) file: |
| 10 | + |
| 11 | +```yaml |
| 12 | +canisters: |
| 13 | + - name: frontend |
| 14 | + recipe: |
| 15 | + type: "@dfinity/static-site@<version>" |
| 16 | + configuration: |
| 17 | + dir: dist |
| 18 | +``` |
| 19 | +
|
| 20 | +> Replace `<version>` with a release version (e.g. `v1.0.0`). See [available versions](https://github.com/dfinity/icp-cli-recipes/releases?q=static-site&expanded=true). |
| 21 | + |
| 22 | +## Configuration Parameters |
| 23 | + |
| 24 | +| Parameter | Type | Required | Description | Default | |
| 25 | +|-----------|------|----------|-------------|---------| |
| 26 | +| dir | string | Yes | The single directory of built assets to synchronize to the canister | - | |
| 27 | +| build | array | No | Shell commands run before sync to produce the asset directory (e.g. `npm run build`) | [] | |
| 28 | +| presync | array | No | Shell commands run at sync time (after the canister exists), with the deployed canister IDs in the environment — see [Pre-sync environment](#pre-sync-environment) | [] | |
| 29 | +| metadata | array | No | Name/value pairs injected into the canister wasm via `ic-wasm` | [] | |
| 30 | + |
| 31 | +> The sync plugin owns the canister's full URL space and accepts **exactly one** asset directory, so `dir` is a single string rather than a list. |
| 32 | + |
| 33 | +## Prerequisites |
| 34 | + |
| 35 | +- The asset directory must already exist or be produced by the `build` commands. |
| 36 | +- Internet connection to download the pinned canister and plugin wasm. |
| 37 | +- `ic-wasm` (bundled with icp-cli) — only required when using the `metadata` option. |
| 38 | + |
| 39 | +> **Note:** If you followed the [icp-cli installation guide](https://github.com/dfinity/icp-cli#installation), `ic-wasm` is already installed. |
| 40 | + |
| 41 | +## Examples |
| 42 | + |
| 43 | +### Basic |
| 44 | + |
| 45 | +```yaml |
| 46 | +canisters: |
| 47 | + - name: website |
| 48 | + recipe: |
| 49 | + type: "@dfinity/static-site@<version>" |
| 50 | + configuration: |
| 51 | + dir: build |
| 52 | +``` |
| 53 | + |
| 54 | +### With a build step and metadata |
| 55 | + |
| 56 | +```yaml |
| 57 | +canisters: |
| 58 | + - name: spa-frontend |
| 59 | + recipe: |
| 60 | + type: "@dfinity/static-site@<version>" |
| 61 | + configuration: |
| 62 | + build: |
| 63 | + - npm ci |
| 64 | + - npm run build |
| 65 | + dir: dist |
| 66 | + metadata: |
| 67 | + - name: "frontend:framework" |
| 68 | + value: "react" |
| 69 | +``` |
| 70 | + |
| 71 | +### With a pre-sync build that needs canister IDs |
| 72 | + |
| 73 | +Build in `presync` rather than `build` when the frontend must embed a canister |
| 74 | +ID — those IDs only exist once the canister is created, which is *after* `build` |
| 75 | +runs: |
| 76 | + |
| 77 | +```yaml |
| 78 | +canisters: |
| 79 | + - name: frontend |
| 80 | + recipe: |
| 81 | + type: "@dfinity/static-site@<version>" |
| 82 | + configuration: |
| 83 | + dir: dist |
| 84 | + presync: |
| 85 | + - npm ci |
| 86 | + # `$ICP_CLI_CID_BACKEND` is the `backend` canister's principal. |
| 87 | + - VITE_CANISTER_ID_BACKEND=$ICP_CLI_CID_BACKEND npm run build |
| 88 | +``` |
| 89 | +
|
| 90 | +## Build Process |
| 91 | +
|
| 92 | +When this recipe runs: |
| 93 | +
|
| 94 | +1. (If `build` is set) runs your build commands to produce the asset directory. This runs *before* the canister exists, so no canister IDs are available yet. |
| 95 | +2. Downloads the pinned certified-assets canister wasm (verified against its `sha256`). |
| 96 | +3. (If `metadata` is set) injects each name/value pair into the wasm with `ic-wasm`. |
| 97 | +4. Installs the canister. |
| 98 | +5. (If `presync` is set) runs your pre-sync commands — the canister IDs now exist and are exported as environment variables (see [Pre-sync environment](#pre-sync-environment)). |
| 99 | +6. Runs the pinned sync plugin to upload and certify the assets in `dir`. |
| 100 | + |
| 101 | +## Pre-sync environment |
| 102 | + |
| 103 | +`presync` commands run via `sh -c` in your project directory, after the canister |
| 104 | +is created but before its assets upload. Unlike `build` (which runs earlier, when |
| 105 | +only `ICP_WASM_OUTPUT_PATH` is available), `presync` sees the deployed canister IDs: |
| 106 | + |
| 107 | +| Variable | Value | |
| 108 | +|----------|-------| |
| 109 | +| `ICP_CLI_CID` | This (frontend) canister's principal. | |
| 110 | +| `ICP_CLI_CID_<NAME>` | Each project canister's principal, keyed by its upper-cased name with non-alphanumeric characters replaced by `_` (e.g. `backend` → `ICP_CLI_CID_BACKEND`). | |
| 111 | +| `ICP_CLI_NETWORK` | The target network name. | |
| 112 | +| `ICP_CLI_ENVIRONMENT` | The target environment name. | |
| 113 | + |
| 114 | +This is what lets a client-side app (Vite, Next static export, etc.) embed the |
| 115 | +canister IDs it will call, at build time. |
| 116 | + |
| 117 | +## Asset Synchronization |
| 118 | + |
| 119 | +The sync plugin diffs your local directory against the canister and uploads only what changed. It serves: |
| 120 | + |
| 121 | +- **Static files** — HTML, CSS, JS, images, fonts, etc., with response certification. |
| 122 | +- **Content encoding** — gzip/Brotli negotiation per request. |
| 123 | +- **Redirects & headers** — driven by `_redirects` / `_headers` files in the asset directory. |
| 124 | +- **404 handling** — a certified fallback plus your own `/404.html` if present. |
| 125 | + |
| 126 | +## Common Issues |
| 127 | + |
| 128 | +**Version mismatch between plugin and canister** — re-deploy with the same recipe version so the canister and plugin are the matched pair this recipe pins. |
| 129 | + |
| 130 | +**Assets directory not found** — ensure the directory in `dir` exists or is produced by your `build` commands. |
| 131 | + |
| 132 | +**`ic-wasm` not found** — only the `metadata` option needs it; install it or drop the `metadata` config. |
| 133 | + |
| 134 | +## Related Recipes |
| 135 | + |
| 136 | +- [Pre-built Recipe](../prebuilt/README.md) — for arbitrary pre-compiled wasm. |
| 137 | +- [Rust Recipe](../rust/README.md) — for backend Rust canisters. |
| 138 | +- [Motoko Recipe](../motoko/README.md) — for backend Motoko canisters. |
| 139 | + |
| 140 | +## Release History |
| 141 | + |
| 142 | +See the [release history](https://github.com/dfinity/icp-cli-recipes/releases?q=static-site&expanded=true) for changelogs and version updates. |
0 commit comments