No native modules, pod installs, or Expo prebuild steps are required. The project is pure Node.js/browser.

Project setup

1. Copy the source/ directory contents into your project root or a dedicated subdirectory (e.g., ./dashy/).

2. Install dependencies from the source/package.json:

   cd dashy
   npm install
   

3. Build the Vue frontend before starting the Express server:

   npm run build
   # outputs to dashy/dist/
   

4. Configure the tsconfig.json path alias if integrating src/ into a TypeScript project:

   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

5. Set environment variables before running the server:

   PORT=8080               # HTTP port (default: 8080 in Docker, 4000 on bare metal)
   HOST=0.0.0.0            # Bind address
   IS_DOCKER=true          # Set if running inside a container
   USER_DATA_DIR=./user-data  # Path to YAML config and custom assets
   SSL_PRIV_KEY_PATH=...   # Optional: path to SSL private key
   SSL_PUB_KEY_PATH=...    # Optional: path to SSL certificate
   

6. Start the server:

   node server.js
   

7. For development with hot reload:

   npm run dev
   # Vite dev server with user-data middleware and HMR
   

8. To run unit tests:

   npm run test
   

Public API

app (Express application) — services/app.js

const app: Express = require('./services/app');

The fully configured Express application with all routes, middleware, static file serving, and authentication wired. Import and pass to http.createServer() or mount as a sub-app in an existing Express project. This is the primary integration point for the backend.

sslServer.startSSLServer — services/ssl-server.js

import sslServer = require('./services/ssl-server');
sslServer.startSSLServer(app: Express): void;

Checks for SSL_PRIV_KEY_PATH and SSL_PUB_KEY_PATH environment variables and, if present, starts an HTTPS server alongside the HTTP one. Call after your HTTP server is created. Safe to call unconditionally — it no-ops if SSL env vars are absent.

printMessage — services/print-message.js

const printMessage: (ip: string, port: number | string, isDocker: boolean) => string
  = require('./services/print-message');

Returns a formatted ASCII welcome string for console output, showing the local and network URLs. Used in server.js after DNS lookup. Useful when embedding Dashy's server startup sequence into a custom launcher script.

serviceWorker — src/utils/InitServiceWorker.js

import serviceWorker from '@/utils/InitServiceWorker';
serviceWorker(): void;

Registers the Vite PWA service worker. Called once during app initialization in main.js before mounting. Only relevant in the frontend context; skip if you are only integrating the Express backend.

i18n — src/utils/i18n.js

import i18n from '@/utils/i18n';
// i18n is a vue-i18n instance; exported so non-component callers can call:
i18n.global.t('some.key');

The shared vue-i18n instance. Installed as a plugin via app.use(i18n) and also exported directly for use in utility modules outside Vue components.

Working examples

Scenario - Embed Dashy's Express app into an existing Node server

You have an existing Express server and want to mount Dashy's full backend (static files, API routes, auth) under a sub-path.

import express from 'express';
import http from 'http';

// Require Dashy's pre-configured Express app
const dashyApp = require('./dashy/services/app');
const sslServer = require('./dashy/services/ssl-server');
const printMessage = require('./dashy/services/print-message');

const rootApp = express();

// Mount Dashy under /dashboard
rootApp.use('/dashboard', dashyApp);

// Your own routes
rootApp.get('/health', (_req, res) => res.json({ status: 'ok' }));

const port = process.env.PORT || 3000;
const host = process.env.HOST || '0.0.0.0';

http.createServer(rootApp).listen(port, host, () => {
  console.log(printMessage('localhost', port, false));
});

// Optionally start SSL alongside
sslServer.startSSLServer(rootApp);

Scenario - Run the Dashy server standalone with custom env configuration

Start Dashy as a standalone process with non-default port and user data directory, matching a production Docker-less deployment.

// launch-dashy.ts (compiled to JS or run via tsx)
import { execSync } from 'child_process';
import path from 'path';

process.env.PORT = '9000';
process.env.HOST = '127.0.0.1';
process.env.USER_DATA_DIR = path.resolve(__dirname, './config');
process.env.IS_DOCKER = 'false';

// Build frontend first if dist/ doesn't exist
try {
  execSync('npm run build', { cwd: path.resolve(__dirname, './dashy'), stdio: 'inherit' });
} catch (e) {
  console.error('Build failed', e);
  process.exit(1);
}

// Now start the server
require('./dashy/server');

Scenario - Initialize the Vue 3 frontend with Dashy's plugins in a custom app

Integrate Dashy's plugin stack (store, router, i18n, modal, toast, directives) into a custom Vue 3 entry point.

// my-main.ts
import { createApp } from 'vue';
import MyApp from './MyApp.vue';

// Dashy's shared infrastructure
import store from './dashy/src/store';
import router from './dashy/src/router';
import i18n from './dashy/src/utils/i18n';
import VModal from './dashy/src/plugins/modal';
import Toast from './dashy/src/utils/Toast';
import clickOutside from './dashy/src/directives/ClickOutside';
import tooltip from './dashy/src/directives/Tooltip';
import Modal from './dashy/src/components/FormElements/Modal.vue';
import ErrorHandler from './dashy/src/utils/logging/ErrorHandler';
import serviceWorker from './dashy/src/utils/InitServiceWorker';

const app = createApp(MyApp);

app.use(store);
app.use(router);
app.use(i18n);
app.use(VModal);
app.use(Toast);

app.component('modal', Modal);
app.directive('clickOutside', clickOutside);
app.directive('tooltip', tooltip);

app.config.errorHandler = (err, _instance, info) => {
  ErrorHandler(`Vue error in ${info}`, err);
};

serviceWorker();

app.mount('#app');

File walkthrough

• server.js - Entry point: resolves port/host from env, creates HTTP server using services/app, starts SSL server, prints welcome message.
• services/app.js - Core Express application: registers all middleware, static file serving from dist/, API routes, and authentication handlers.
• services/ssl-server.js - Conditionally starts an HTTPS server when SSL cert env vars are present.
• services/print-message.js - Returns a formatted startup banner string with local and network access URLs.
• src/main.js - Vue 3 app factory: registers all plugins, global components, directives, error handlers, and mounts to #app.
• src/App.vue - Root Vue component (Dashy) that bootstraps the layout.
• src/store/ - Vuex store for application state (config, user auth state, UI preferences).
• src/router/ - Vue Router configuration defining all page routes.
• src/utils/ - Utility modules: i18n setup, service worker init, error reporting, auth helpers (Keycloak, OIDC, Header), Toast notifications.
• src/components/ - All Vue components: dashboard items, widgets, form elements, modals, theming UI, etc.
• src/directives/ - Custom Vue directives: ClickOutside (for closing overlays) and Tooltip.
• src/plugins/ - Vue plugins: modal plugin that adds $modal.show()/$modal.hide() to all components.
• user-data/ - Runtime YAML config files (e.g., conf.yml) and user assets; served in dev by Vite middleware and copied to dist/ on build.
• vite.config.mjs - Vite config: Vue plugin, PWA, SVG loader, user-data dev middleware, env prefix VITE_ and DASHY_.
• vitest.config.mjs - Test runner config: happy-dom environment, global test functions, @ alias matching Vite config.
• eslint.config.mjs - Flat ESLint config for ES2022 + Vue 3 flat/recommended + import-x plugin.
• public/ - Static files copied verbatim to dist/ (favicons, manifest, etc.).
• docs/ - Markdown documentation for all Dashy features; not bundled into the app.

Common pitfalls and fixes

• dist/ not found at server startup: server.js serves files from dist/ which requires a prior npm run build; always build before running node server.js.
• @ alias not resolved in your IDE or bundler: Add "paths": { "@/*": ["./src/*"] } to tsconfig.json and mirror the alias in your own Vite/Webpack config as shown in vite.config.mjs.
• Environment variables not picked up by Vite: Only variables prefixed VITE_ or DASHY_ are exposed to the frontend bundle (set via envPrefix in vite.config.mjs); backend-only vars (e.g., PORT, IS_DOCKER) are Node.js process.env only.
• User data YAML not served in dev mode: The serveUserData Vite plugin reads from the path in USER_DATA_DIR env var (default ./user-data); set this env var if your config lives elsewhere.
• ESM/CJS interop in server.js: server.js and all services/ files use CommonJS (require); do not rename them to .mjs or add "type": "module" to package.json without converting all require calls to import.
• SSL server silently skipped: sslServer.startSSLServer() no-ops if SSL_PRIV_KEY_PATH or SSL_PUB_KEY_PATH are unset; verify both env vars point to readable files if HTTPS is expected.

Vibe-coding prompt template

I have purchased the "dashy" source block. The source is in ./dashy/ and the
integration guide is at ./USAGE.md. The upstream package is user@example.com (Vue 3 + Express).

Please integrate Dashy into my existing project step-by-step:

1. Read USAGE.md fully before writing any code.
2. Mount the Dashy Express app (./dashy/services/app.js) into my existing
   Express server at the /dashboard sub-path.
3. Wire the SSL server helper (./dashy/services/ssl-server.js) to start
   alongside my main HTTP server.
4. Ensure the build step (npm run build inside ./dashy/) runs before the
   server starts; add it to my build pipeline or startup script.
5. If I need the Vue frontend, show me how to integrate Dashy's store, router,
   i18n, and plugin registration from ./dashy/src/main.js into my own
   Vue 3 entry point without duplicating the app mount.
6. List any environment variables I must set (PORT, HOST, IS_DOCKER,
   USER_DATA_DIR, SSL_PRIV_KEY_PATH, SSL_PUB_KEY_PATH) and where to place them.
7. Do not invent any API that is not documented in USAGE.md or visible in the
   source files under ./dashy/.
8. Show complete, runnable code for each integration step.

License and credit

Dashy is released under the MIT License. See source/LICENSE for the full text. Upstream project: dashy on npm (version 4.0.6) and github.com/Lissy93/dashy.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。