Skills missing npm versions, Vite config, and complete frontend scaffold

[marc0olo]

Context

While using the internet-identity, asset-canister, and icp-cli skills together to add II authentication with a frontend to a Motoko project, an AI agent hit four sequential build/runtime failures before getting a working result. Two of these are already addressed by #91 (wrong II canister ID, missing fetch binding) and the related JS SDK fix. The remaining issues are about missing information in the skills.

Problem

The skills don't contain enough information for an agent (or developer) to produce a working frontend + II integration on the first attempt. Specifically:

1. No npm package versions anywhere. The internet-identity skill lists @icp-sdk/auth and @icp-sdk/core as prerequisites but without version numbers. The binding-generation.md reference shows @icp-sdk/bindgen usage but no version. An agent guessed ^0.1.0 — the actual versions are 5.x and 0.2.x, causing npm install to fail.

2. No Vite build.target guidance. The frontend code examples use top-level await (e.g., await AuthClient.create()), but Vite's default build target (es2020) doesn't support it. The build fails with "Top-level await is not available in the configured target environment". No skill mentions that build.target: "esnext" is required.

3. No complete frontend project scaffold. Building a working frontend requires piecing together fragments from three skills and two reference docs: icp.yaml from asset-canister, auth code from internet-identity, Vite plugin config from icp-cli/references/binding-generation.md, dev server setup from icp-cli/references/dev-server.md, and .ic-assets.json5 from asset-canister. There is no single place that shows a complete, working package.json + vite.config.js + index.html.

Proposed changes

1. internet-identity/SKILL.md — add npm versions to prerequisites

Current:

- Frontend: `@icp-sdk/auth`, `@icp-sdk/core`

Proposed:

- Frontend: `@icp-sdk/auth` (>= 5.0.0), `@icp-sdk/core` (>= 5.0.0)

2. asset-canister/SKILL.md — add complete Vite project scaffold

Add a section with a working minimal frontend setup:

• package.json with @icp-sdk/core, @icp-sdk/bindgen, and vite at correct versions
• vite.config.js with:
  • build.target: "esnext" (required for top-level await)
  • @icp-sdk/bindgen plugin configured
  • Dev server config (currently buried in icp-cli/references/dev-server.md)
• Minimal index.html entry point

This belongs in asset-canister because any frontend on IC needs this base, regardless of auth method.

3. icp-cli/references/binding-generation.md — add @icp-sdk/bindgen version

The reference shows icpBindgen() usage but doesn't state which version to install. Add >= 0.2.0.

Already addressed

• Wrong II canister ID fallback → fix(internet-identity): hardcode II canister ID, add fetch binding #91
• Missing fetch: window.fetch.bind(window) → fix(internet-identity): hardcode II canister ID, add fetch binding #91
• Root cause fetch binding fix in JS SDK → linked in fix(internet-identity): hardcode II canister ID, add fetch binding #91

[marc0olo]

build.target: "esnext" is not the right fix

I investigated the icp-js-bindgen source code and the skill code examples to trace where the top-level await failure actually comes from.

The bindgen output has no top-level await

Looking at the generated snapshots, the bindgen output is clean:

• createActor() is synchronous (uses HttpAgent.createSync)
• All await calls are inside async class methods
• The declarations JS file (*.did.js) is fully synchronous

So the Vite build error is not caused by bindgen.

The top-level await comes from the skill code examples

The internet-identity skill shows this pattern at line 85:

const authClient = await AuthClient.create();

This is a bare top-level await — not wrapped in any function. When an agent copies this into a module bundled by Vite, the build fails because Vite's default target (modules → es2020) doesn't support top-level await (ES2022).

The same pattern appears in wallet-integration (line 161: await IcrcWallet.connect(...)) and asset-canister (line 168: await HttpAgent.create(...)).

Why esnext is a bad recommendation

• esnext disables all transpilation — output may not work in older browsers
• It's a sledgehammer for a scalpel problem
• es2022 would be the minimum target that supports TLA, but even that is unnecessary here

Better fix: wrap examples in async functions

Instead of changing the build target, the code examples should not use top-level await:

async function init() {
  const authClient = await AuthClient.create();
  // ...rest of auth flow
}
init();

This works with any Vite build target and is better practice for frontend code. The skills that need updating:

• internet-identity/SKILL.md — await AuthClient.create()
• wallet-integration/SKILL.md — await IcrcWallet.connect(...), await IcpWallet.connect(...)
• asset-canister/SKILL.md — await HttpAgent.create(...)

Proposal

I'd suggest replacing the build.target: "esnext" recommendation in this issue with wrapping the code examples in async functions. This also makes the examples more realistic — real apps initialize auth inside a function, not at the module top level.

The npm version and frontend scaffold points from this issue are still valid and should be addressed separately.