docs: frontend frameworks guide

[marc0olo]

Summary

• Asset canister ic_env cookie for runtime canister ID injection
• React/Vite: icp.yaml, vite.config.ts with @icp-sdk/bindgen plugin, SPA routing
• Vue/Vite, Svelte/SvelteKit, Next.js (output: export), Unity WebGL, Godot HTML5, static sites
• Per-framework build output directory configuration

Sync recommendation

informed by dfinity/icp-cli-templates — hello-world; dfinity/examples — hosting/react, unity-webgl-template, godot-html5-template

[marc0olo]

Review: Frontend Frameworks

Must fix

• icp canister id does not exist: Line 356 uses icp canister id frontend to retrieve the canister ID. This subcommand does not exist in icp-cli. Verified against .sources/icp-cli/docs/reference/cli.md — the available icp canister subcommands are: call, create, delete, install, list, logs, metadata, migrate-id, settings, snapshot. There is no id subcommand. The correct command to get a canister ID is icp canister settings show frontend -i (using the -i/--id-only flag).

• vite.config.ts proxy port hardcoded without guidance: The React vite.config.ts snippet (line 76) proxies /api to http://127.0.0.1:8000. This matches the hello-world template and icp-cli defaults. However, the comment on line 68–72 tells readers to "replace IC_ROOT_KEY_HEX and BACKEND_CANISTER_ID with values from your local replica after running icp network start -d and icp deploy" but gives no instruction on how to obtain the root key hex. The hello-world template (.sources/icp-cli-templates/hello-world/frontend/app/vite.config.ts) defines named constants at the top of the file with an example value, making it clear what to substitute. The inline approach used in the page (with <IC_ROOT_KEY_HEX> placeholders embedded inside the cookie string) is harder to read and likely to cause copy-paste errors. Recommend adopting the template's named-constants pattern.

Suggestions

• Content brief gap — auth setup not covered: The stub's <\!-- Content Brief --> explicitly mentions "auth setup with @icp-sdk/auth" as a required topic. The page does link to Internet Identity in the Next steps section but provides no framework-specific auth integration. This is a meaningful gap for developers who want to add authentication to their React or Vue app. Consider adding a short section or note with a pointer to the authentication guide and a mention that auth is framework-agnostic.

• Vue section omits ic_env cookie simulation: The React section shows the full vite.config.ts including the server.headers block for simulating the ic_env cookie in dev mode. The Vue section (lines 151–171) omits this entirely — it only shows the proxy block. A developer using Vue would encounter a runtime error when getCanisterEnv() throws because the cookie is absent during local development. Either show the full Vue vite.config.ts with the cookie simulation, or add a note after the Vue snippet explaining that the same server.headers setup from the React section applies.

• SPA .ic-assets.json5 config structure: The SPA routing snippet (lines 126–138) splits security_policy and enable_aliasing into two separate rule objects matching on **/*. The asset-canister skill's recommended pattern consolidates these with a comment explaining the rule order. The page's split approach works, but adding a brief comment noting why two rules are needed (settings that interact) would help readers who modify the file.

• icp deploy -e ic not shown in framework sections: The Deploy section at the bottom mentions mainnet deployment. However, none of the per-framework sections reference mainnet deployment. This is fine structurally, but the page could reference the Deploy section earlier (e.g., "See the Deploy section below for mainnet deployment").

Verified

• icp.yaml structure: All canisters[].recipe.type, configuration.dir, and configuration.build fields match .sources/icp-cli-recipes/recipes/asset-canister/recipe.hbs and .sources/examples/hosting/react/icp.yaml.
• Unity icp.yaml snippet: Exact match to .sources/examples/hosting/unity-webgl-template/icp.yaml.
• Godot icp.yaml snippet: Exact match to .sources/examples/hosting/godot-html5-template/icp.yaml.
• getCanisterEnv import path: @icp-sdk/core/agent/canister-env confirmed in icp-js-sdk-docs canister-environment.mdx.
• icpBindgen Vite plugin import: @icp-sdk/bindgen/plugins/vite confirmed in icp-js-sdk-docs bindgen zip.
• createActor pattern: Lines 97–118 match the "Usage with an Actor" pattern in the SDK canister-environment guide exactly.
• IC_ROOT_KEY type: getCanisterEnv() returns IC_ROOT_KEY as Uint8Array (confirmed). The actor creation code rootKey: \!import.meta.env.DEV ? canisterEnv.IC_ROOT_KEY : undefined is correct.
• icp network start -d flag: -d is the short form of --background, confirmed in icp-cli reference.
• icp deploy -e ic flag: Confirmed via -e/--environment on icp deploy in icp-cli reference.
• Install command: npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm confirmed in .sources/icp-cli/docs/quickstart.md.
• Internal links: asset-canister.md exists in same directory. ../authentication/internet-identity.md resolves to internet-identity.mdx (confirmed). ../../getting-started/project-structure.md resolves to project-structure.mdx (confirmed).
• External URLs: cli.internetcomputer.org and js.icp.build are in the approved linking rules in content-authoring.md. GitHub example links verified against .sources/examples/hosting/.
• SvelteKit adapter-static build dir: Default build dir confirmed; the config explicitly sets pages: "build" and assets: "build" which is correct.
• Upstream: comment: Present at end of file with all relevant source repos listed.
• Frontmatter: Complete — title, description, sidebar.order all present.
• No dfx references: Confirmed.
• No mo:base imports: N/A — no Motoko code on this page.
• File is .md not .mdx: Correct — no interactive components needed.

[marc0olo]

<!-- feedback-addressed -->

Feedback addressed for PR #89 — Frontend Frameworks

Changes applied

1. Fixed non-existent icp canister id command (must fix) — Replaced icp canister id frontend with icp canister settings show frontend -i. Verified against .sources/icp-cli/docs/reference/cli.md: the icp canister subcommands are call, create, delete, install, list, logs, metadata, migrate-id, settings, snapshot. No id subcommand exists. The -i / --id-only flag is documented on icp canister settings show.

2. Adopted named-constants pattern for vite.config.ts (must fix) — Replaced embedded <IC_ROOT_KEY_HEX> and <BACKEND_CANISTER_ID> placeholders inside the cookie string with named constants declared at the top of the file. Matches the pattern used in .sources/icp-cli-templates/hello-world/frontend/app/vite.config.ts. Also switched the template literal from a string to a backtick literal so the constants interpolate correctly.

3. Added note to Vue section about ic_env cookie simulation (suggestion) — Added a sentence after the Vue vite.config.ts snippet explaining that if the Vue app calls getCanisterEnv(), it needs the same server.headers block from the React section to avoid a runtime error during local development.

4. Added Authentication section (suggestion) — Added a brief ## Authentication section between the Vue and Svelte sections noting that @icp-sdk/auth and Internet Identity are framework-agnostic, with a link to the Internet Identity guide. Addresses the content brief gap.

5. Added explanatory comments to SPA .ic-assets.json5 snippet (suggestion) — Added inline comments explaining why two separate rules are needed and labeling the SPA fallback behavior.

Items skipped

• "Reference the Deploy section earlier from framework sections" (suggestion) — Skipped. Adding "See the Deploy section below" cross-references in each framework section adds repetitive boilerplate without meaningful value. Developers read to the Deploy section naturally. Page structure kept clean.