@skyroc/web-admin-runtime

apps/admin
  ├─ bootstrap.tsx                 组织启动顺序
  ├─ plugins/index.ts              把应用 env / UI / router 适配成 runtime options
  ├─ plugins/app.tsx               应用版本更新提示的通知 UI 与路由行为
  └─ plugins/assets.ts             样式和 Vite 虚拟模块副作用入口

@skyroc/web-admin-runtime
  ├─ setupAdminRuntimePlugins()    运行时插件聚合入口
  ├─ setupDayjs()                  Dayjs localeData 与可选初始语言同步
  ├─ setupIconifyOffline()         Iconify API provider 注册
  ├─ setupNProgress()              NProgress 配置与实例回传
  ├─ setupAppVersionNotification() index.html buildTime 更新检测
  └─ getHtmlBuildTime()            从 HTML meta 中读取 buildTime

@skyroc/web-admin-vite
  └─ 注入 BUILD_TIME，并在 index.html 写入 buildTime meta

import { setupAdminRuntimePlugins } from '@skyroc/web-admin-runtime';
import type { SetupDayjsOptions, SetupIconifyOfflineOptions, SetupNProgressOptions } from '@skyroc/web-admin-runtime';

import { initNProgress } from '@/config';

import { createAdminAppVersionNotificationPluginOptions } from './app';

const adminDayjsPluginOptions = {
  withLocaleData: true
} satisfies SetupDayjsOptions;

const adminIconifyOfflinePluginOptions = {
  apiUrl: import.meta.env.VITE_ICONIFY_URL
} satisfies SetupIconifyOfflineOptions;

const adminNProgressPluginOptions = {
  easing: 'ease',
  onReady: initNProgress,
  parent: '.root',
  speed: 500
} satisfies SetupNProgressOptions;

export function setupAdminPlugins() {
  return setupAdminRuntimePlugins({
    dayjs: adminDayjsPluginOptions,
    appVersionNotification: createAdminAppVersionNotificationPluginOptions(),
    iconifyOffline: adminIconifyOfflinePluginOptions,
    nprogress: adminNProgressPluginOptions
  });
}

import { createRoot } from 'react-dom/client';

import App from './App';
import { setupI18n } from './locales';
import { setupAdminPlugins } from './plugins';
import './plugins/assets';

async function setupApp() {
  const container = document.getElementById('app');

  if (!container) return;

  setupAdminPlugins();

  await setupI18n();

  createRoot(container).render(<App />);
}

setupApp();

import { setupAdminRuntimePlugins } from '@skyroc/web-admin-runtime';

setupAdminRuntimePlugins({
  dayjs: {},
  iconifyOffline: {},
  nprogress: {},
  appVersionNotification: {
    currentBuildTime: BUILD_TIME,
    enabled: import.meta.env.PROD,
    onUpdateAvailable(context) {
      // host app notification
    }
  }
});

setupAdminRuntimePlugins({
  dayjs: {
    withLocaleData: false
  },
  iconifyOffline: false,
  nprogress: {
    parent: '#app',
    speed: 300
  },
  appVersionNotification: false
});

const cleanup = setupAdminRuntimePlugins({
  appVersionNotification: {
    currentBuildTime: BUILD_TIME,
    enabled: import.meta.env.PROD,
    onUpdateAvailable() {}
  }
});

cleanup();

import { setupDayjs } from '@skyroc/web-admin-runtime';

setupDayjs({
  withLocaleData: true
});

import { locale } from 'dayjs';
import 'dayjs/locale/en';
import 'dayjs/locale/zh-cn';

function syncLocales(lang: 'zh-CN' | 'en-US') {
  const localeMap = {
    'zh-CN': 'zh-cn',
    'en-US': 'en'
  };

  locale(localeMap[lang]);
}

import { setupIconifyOffline } from '@skyroc/web-admin-runtime';

setupIconifyOffline({
  apiUrl: import.meta.env.VITE_ICONIFY_URL,
  provider: ''
});

// apps/admin/src/plugins/assets.ts
import 'uno.css';
import 'virtual:svg-icons-register';
import '../styles/css/global.css';

import { setupNProgress } from '@skyroc/web-admin-runtime';

setupNProgress({
  easing: 'ease',
  parent: '.root',
  speed: 500,
  onReady(nprogress) {
    // save instance to host config if needed
  }
});

import type { NProgress } from 'nprogress';

const progress = {
  instance: null as NProgress | null
};

export function initNProgress(nprogress: NProgress) {
  progress.instance = nprogress;
}

import { setupAppVersionNotification } from '@skyroc/web-admin-runtime';

setupAppVersionNotification({
  baseUrl: import.meta.env.VITE_BASE_URL || '/',
  currentBuildTime: BUILD_TIME,
  enabled: import.meta.env.PROD,
  interval: 3 * 60 * 1000,
  onError(error) {
    console.error('Failed to check app version:', error);
  },
  onUpdateAvailable({ latestBuildTime, markPromptClosed }) {
    // show host app notification
  }
});

import type { SetupAppVersionNotificationOptions } from '@skyroc/web-admin-runtime';

import { destroyNotification, globalConfig, showNotification } from '@/config';
import { router } from '@/features/router';

import { $t } from '../locales';

const UPDATE_NOTIFICATION_KEY = 'update-notification';

export function createAdminAppVersionNotificationPluginOptions(): SetupAppVersionNotificationOptions {
  return {
    baseUrl: import.meta.env.VITE_BASE_URL || '/',
    currentBuildTime: BUILD_TIME,
    enabled: globalConfig.automaticallyDetectUpdate && import.meta.env.PROD,
    onError(error) {
      console.error('Failed to get HTML build time:', error);
    },
    onUpdateAvailable({ markPromptClosed }) {
      function handleCancel() {
        destroyNotification(UPDATE_NOTIFICATION_KEY);
        markPromptClosed();
      }

      function handleOk() {
        router.navigate({ to: '.' });
      }

      showNotification({
        actions: (
          <div className="w-325px flex justify-end gap-3">
            <AButton
              key="cancel"
              onClick={handleCancel}
            >
              {$t('system.updateCancel')}
            </AButton>
            <AButton
              key="ok"
              type="primary"
              onClick={handleOk}
            >
              {$t('system.updateConfirm')}
            </AButton>
          </div>
        ),
        description: $t('system.updateContent'),
        key: UPDATE_NOTIFICATION_KEY,
        onClose: markPromptClosed,
        title: $t('system.updateTitle')
      });
    }
  };
}

import { getHtmlBuildTime } from '@skyroc/web-admin-runtime';

const latestBuildTime = await getHtmlBuildTime({
  baseUrl: '/',
  fetcher: window.fetch.bind(window)
});

${baseUrl}index.html?time=${Date.now()}

<meta
  name="buildTime"
  content="2026-05-28 10:00:00"
/>

setupTheme({
  buildTime: BUILD_TIME
});

setupAdminLayouts({
  routeTree,
  storage
  // ...
});

setupAdminPlugins();

await setupI18n();

createRoot(container).render(<App />);

interface SetupAdminRuntimePluginsOptions {
  appVersionNotification?: false | SetupAppVersionNotificationOptions;
  dayjs?: false | SetupDayjsOptions;
  iconifyOffline?: false | SetupIconifyOfflineOptions;
  nprogress?: false | SetupNProgressOptions;
}

interface SetupDayjsOptions {
  syncLocale?: () => void;
  withLocaleData?: boolean;
}

interface SetupIconifyOfflineOptions {
  apiUrl?: string;
  provider?: string;
}

interface SetupNProgressOptions {
  easing?: string;
  onReady?: (nprogress: NProgress) => void;
  parent?: string;
  speed?: number;
}

interface SetupAppVersionNotificationOptions {
  baseUrl?: string;
  currentBuildTime: string;
  enabled: boolean;
  interval?: number;
  onError?: (error: unknown) => void;
  onUpdateAvailable: (context: AppUpdateAvailableContext) => void;
}

interface AppUpdateAvailableContext {
  currentBuildTime: string;
  latestBuildTime: string;
  markPromptClosed: () => void;
}

pnpm --filter @skyroc/web-admin-runtime test
pnpm --filter @skyroc/web-admin-runtime typecheck
pnpm --filter @skyroc/web-admin-runtime build
pnpm --filter skyroc-admin typecheck
pnpm --filter skyroc-admin build:test

pnpm --dir docs/docs types:check
pnpm --dir docs/docs build

pnpm exec oxfmt --check docs/docs/content/docs/web/admin-runtime.mdx docs/docs/content/docs/web/meta.json

import 'uno.css';
import 'virtual:svg-icons-register';
import '../styles/css/global.css';