build-and-deploy

You are packaging an Even Hub G2 app for distribution. Follow the steps below carefully, validating each stage before proceeding.

Packaging Workflow

Follow these steps in order:

Step 1 — Validate app.json

1. Locate app.json in the project root.
2. Read the file and validate every field against the field reference below.
3. If any field is missing, has the wrong type, or fails a validation rule, report the exact error and fix it (with user confirmation if the fix changes meaningful values like package_id or name).
4. Do not proceed until app.json is valid.

Step 2 — Build

Run the build command from the project root:

npm run build

Check that the build succeeds (exit code 0) and that the output folder (typically dist/) exists and is non-empty.

Step 3 — Pack into .ehpk

Run the pack command, substituting the app name for <name>:

npx evenhub pack app.json dist -o <name>.ehpk

Use the value of the name field from app.json (lowercased, spaces replaced with hyphens) as <name>. For example, if name is "Weather Now", use weather-now.ehpk.

Step 4 — Verify output

Confirm the .ehpk file was created:

ls -lh <name>.ehpk

If the file is missing, check the error output from the pack command and consult the troubleshooting table below.

Step 5 — Distribute

Submit the .ehpk file to the Even Hub developer portal for review and publication.

app.json Field Reference

Every field is required unless noted. Validate each field before running evenhub pack.

Minimal valid app.json example

{
  "package_id": "com.example.weatherapp",
  "edition": "202601",
  "name": "Weather Now",
  "version": "1.0.0",
  "min_app_version": "2.0.0",
  "min_sdk_version": "0.0.12",
  "entrypoint": "index.html",
  "permissions": [],
  "supported_languages": ["en"]
}

Permissions Reference

permissions must be an array of objects. Each object has:

Valid permission names

• network — outbound network access (requires whitelist)
• location — device GPS/location data
• g2-microphone — microphone on the G2 glasses
• phone-microphone — microphone on the paired phone
• album — access to the photo album
• camera — access to the camera

Example

"permissions": [
  {
    "name": "network",
    "desc": "Fetches weather data from the API.",
    "whitelist": ["https://api.weather.com"]
  },
  {
    "name": "g2-microphone",
    "desc": "Enables voice commands for hands-free control."
  }
]

Common mistake

Do NOT use a key-value map format:

// WRONG
"permissions": { "network": ["example.com"] }

// CORRECT
"permissions": [{ "name": "network", "desc": "...", "whitelist": ["example.com"] }]

CORS in the WebView

The Even App runs your plugin inside a real browser engine (Chromium on Android, WKWebView on iOS). Full CORS enforcement applies. The app.json network whitelist is an Even-level permission check — it does NOT bypass CORS. You need BOTH:

1. The domain whitelisted in app.json permissions.network.whitelist, AND
2. The remote API to respond with the correct CORS headers (Access-Control-Allow-Origin, etc.)

If the API you're calling doesn't send CORS headers, fetch() will fail with a network error even though the domain is whitelisted.

Vite dev proxy

Use a Vite proxy to avoid CORS during local development:

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        rewrite: (p) => p.replace(/^\/api/, ''),
      },
    },
  },
})

This proxy only works in dev. For the production .ehpk, the WebView makes requests directly — your API must have CORS headers, or you must route through your own proxy.

Free CORS proxy services are unreliable

Public proxies like corsproxy.io, allorigins.win, and api.codetabs.com go down, return 403s, or timeout without warning. If your app depends on a third-party API without CORS, deploy your own Cloudflare Worker (free tier, ~5 min setup) or find a mirror that serves CORS headers natively.

evenhub pack Options

npx evenhub pack <app.json> <build-folder> [options]

Troubleshooting

Distribution

Once the .ehpk file is verified, submit it to the Even Hub developer portal for review and publication. The portal will validate the package, run compatibility checks, and make the app available to Even Hub G2 users after approval.

Task

$ARGUMENTS