Crate my_canister_dashboard 

My Canister Dashboard

Dashboard assets and management utilities for user-owned dapps on the Internet Computer.

Integrates with AssetRouter for asset certification.

Features

• Embedded Dashboard UI - Pre-built HTML/CSS/JS dashboard served at /canister-dashboard
• Internet Identity Integration - Manage II principal for authentication
• Alternative Origins - Configure /.well-known/ii-alternative-origins for II domain delegation
• Automatic Top-up - Schedule periodic cycles top-ups when balance falls below threshold
• Guard Functions - Restrict endpoints to controllers or II principal
• Light/Dark Theme - Automatic theme detection with manual toggle
• Copy Buttons - One-click copy for principals, accounts, and hashes

Setup

use ic_asset_certification::AssetRouter;
use my_canister_dashboard::setup;
use std::cell::RefCell;
use ic_cdk::{api::certified_data_set, init};

thread_local! {
    static ASSET_ROUTER: RefCell<AssetRouter<'static>> = RefCell::new(
        AssetRouter::new()
    );
}

#[init]
fn init() {
    ASSET_ROUTER.with(|router| {
        let mut router = router.borrow_mut();
        setup::setup_dashboard_assets(
            &mut router,
            Some(vec!["https://mycanister.app".to_string()]),
        ).expect("Failed to setup dashboard");
        certified_data_set(router.root_hash());
    });
}

Management Functions

Expose these in your canister to enable dashboard functionality:

II Principal Management

use my_canister_dashboard::{
    ManageIIPrincipalArg, ManageIIPrincipalResult,
    guards::only_canister_controllers_guard,
};
use ic_cdk::update;

#[update(guard = "only_canister_controllers_guard")]
fn manage_ii_principal(arg: ManageIIPrincipalArg) -> ManageIIPrincipalResult {
    my_canister_dashboard::manage_ii_principal(arg)
}

Alternative Origins Management

use my_canister_dashboard::{
    ManageAlternativeOriginsArg, ManageAlternativeOriginsResult,
    guards::only_canister_controllers_guard,
};
use ic_cdk::update;

#[update(guard = "only_canister_controllers_guard")]
fn manage_alternative_origins(arg: ManageAlternativeOriginsArg) -> ManageAlternativeOriginsResult {
    ASSET_ROUTER.with(|router| {
        my_canister_dashboard::manage_alternative_origins(&mut router.borrow_mut(), arg)
    })
}

Automatic Top-up Rules

use my_canister_dashboard::{
    ManageTopUpRuleArg, ManageTopUpRuleResult,
    guards::only_ii_principal_guard,
};
use ic_cdk::update;

#[update(guard = "only_ii_principal_guard")]
fn manage_top_up_rule(arg: ManageTopUpRuleArg) -> ManageTopUpRuleResult {
    my_canister_dashboard::manage_top_up_rule(arg)
}

Guards

Two guard functions for protecting endpoints:

• only_canister_controllers_guard() - Allows only canister controllers
• only_ii_principal_guard() - Allows only the configured II principal

use my_canister_dashboard::guards::{only_canister_controllers_guard, only_ii_principal_guard};
use ic_cdk::update;

#[update(guard = "only_canister_controllers_guard")]
fn admin_only_function() { /* ... */ }

#[update(guard = "only_ii_principal_guard")]
fn user_only_function() { /* ... */ }

Usage with my_canister_frontend

When using the my_canister_frontend crate, add dashboard assets to its internal router instead of managing your own AssetRouter:

use ic_cdk::init;
use include_dir::{include_dir, Dir};
use my_canister_dashboard::setup::setup_dashboard_assets;
use my_canister_frontend::setup_frontend;
use my_canister_frontend::asset_router::with_asset_router_mut;

static FRONTEND_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/../dapp-frontend/dist");

#[init]
fn init() {
    // Setup frontend assets with certification
    setup_frontend(&FRONTEND_DIR).expect("Failed to setup frontend");

    // Add dashboard UI to the frontend's internal router
    with_asset_router_mut(|router| {
        let origins = vec!["https://mycanister.app".to_string()];
        setup_dashboard_assets(router, Some(origins))
            .expect("Failed to setup dashboard assets");
    });
}

See the examples directory for complete working implementations.

Asset Paths

The dashboard assets are served at these paths:

Constant	Path
CANISTER_DASHBOARD_HTML_PATH	/canister-dashboard
CANISTER_DASHBOARD_JS_PATH	/canister-dashboard/index.js
CANISTER_DASHBOARD_CSS_PATH	/canister-dashboard/style.css
ALTERNATIVE_ORIGINS_PATH	/.well-known/ii-alternative-origins

Vite Plugin

For local development, use @web3nl/vite-plugin-canister-dapp to configure the development environment.

License

MIT

Modules

guards

setup

Structs

TopUpRule

Configuration for automatic cycles top-up.

WasmStatus

Status information for a user-owned dapp’s WASM module.

Enums

CyclesAmount

Predefined cycles amounts for thresholds and top-up amounts.

ManageAlternativeOriginsArg

Arguments for managing alternative origins.

ManageAlternativeOriginsResult

Result of managing alternative origins.

ManageIIPrincipalArg

Arguments for managing the Internet Identity principal at user dapp domain.

ManageIIPrincipalResult

Result of managing the Internet Identity principal.

ManageTopUpRuleArg

Arguments for managing automatic top-up rules.

ManageTopUpRuleResult

Result of managing top-up rules.

TopUpInterval

Interval at which to check cycles balance and potentially top up.

Constants

ALTERNATIVE_ORIGINS_PATH

Path to the Internet Identity alternative origins file

ASSET_HASHES_JSON

SHA-256 hashes of dashboard frontend assets for each published version. Used by the acceptance test library to verify deployed canisters serve unmodified dashboard assets.

CANISTER_DASHBOARD_CSS_PATH

Path to the canister dashboard CSS file

CANISTER_DASHBOARD_HTML_PATH

Path to the canister dashboard HTML endpoint

CANISTER_DASHBOARD_JS_PATH

Path to the canister dashboard JavaScript file

Functions

manage_alternative_origins

Manages alternative origins for Internet Identity.

manage_ii_principal

Manages the storage for Internet Identity principal at user dapp domain

manage_top_up_rule

Manages automatic cycles top-up rules.