Local development

Abstract

Local AXIS development is a multi-process topology. AXIS is a Solid app under Vite; evaluation usually hits Flask; optional cloud/storage/stream features hit the Worker.

Conceptual model

Interface surface — commands

Bootstrap (CLI-first)

axis install   # app + worker + CLI
axis doctor    # missing worker/wrangler.toml is a warning until `axis setup`

Frontend (preferred product path)

bun run dev            # Vite + Solid → typically http://127.0.0.1:3000
# or: bun run axis dev

Desktop (optional Tauri shell)

bun run desktop:dev    # Vite + native window (see devops/desktop)
# or: bun run axis dev desktop

Flask Pro API (engine backend)

From the pyne checkout (sister repo; clone hoox-sh/pyne as ../pyne — the local directory is sometimes still named pynescript):

make -C ../pyne run   # Flask → :5002

Set PWA endpoint to http://127.0.0.1:5002 for the server engine. Workers Manager and Settings can probe this URL.

Worker

bun run axis dev worker   # http://127.0.0.1:8787
# or: cd worker && bun run dev

Point cloud storage / Worker endpoint at http://127.0.0.1:8787. For /api/run proxy, set Worker EXTERNAL_BACKEND=http://127.0.0.1:5002 (works on local wrangler; not on Cloudflare® edge).

AXIS CLI

Preferred operator entry for install / doctor / setup / deploy — see AXIS CLI:

bun run axis install
bun run axis doctor
bun run axis setup
bun run axis dev worker

Makefile helpers

Use bun run dev for the product, or bun run build and serve dist/. The pre-Solid server.ts static tree was removed in 2.21.0 (legacy shell).

Storybook (component lab)

bun run storybook        # isolated UI on :6006 (`storybook-solidjs-vite`)
bun run build-storybook  # static build

Stories live in src/stories/ (topbar fields, theme tokens, studio primitives, draw tools, toasts, …). Covers chrome in isolation — no Flask/Worker needed.

Debug mode (chart + engine)

Turn it on in the app: Settings → General → Debug logs, or open Studio → Debug in the left rail for the switch plus a live view of the ring (scope/search filters, pause, follow, copy, download, clear). It is stored as localStorage.axis.debug and applies immediately — no rebuild. The boot banner prints [axis:debug] chart/engine logging on; toggling mid-session prints it too. Filter DevTools by [axis:.

For a build that ships with logging on, set VITE_AXIS_DEBUG=1 in .env (alias VITE_DEBUG) and restart bun run dev. Vite inlines that flag at build time, and it wins over the Settings toggle (the toggle then shows Forced by .env). e2e forces the flag off (playwright.config.ts).

Forming ticks and live deltas log at most about once per second so a live feed cannot freeze the console. Snapshots, window slides, menu actions, and apply aborts always log.

Lines are also written to a rotating localStorage ring (axis.debug.log.0 is current, .1–.3 previous rotations, 64 KiB each). The oldest file is dropped on rotate. Writes coalesce every 250 ms and flush on tab hide. Download or clear the ring from Settings → General → Debug logs, from System Logs (download icon while debug is on), or with window.__AXIS_DEBUG__.download() in DevTools. window.__AXIS_DEBUG__.read() / .clear() / .stats() / .set(true|false) inspect and flip the runtime flag.

Vite inlines the env flag at build time; the Settings toggle writes localStorage.axis.debug instead and needs no reload.

Internals — useful paths

Worked loop

1. Terminal A: make run (Flask).
2. Terminal B: bun run dev.
3. Open Vite URL; set engine Server-Side, endpoint http://127.0.0.1:5002.
4. Load mock-walk if venues are blocked.
5. Optional Terminal C: Worker with ALLOW_OPEN_KEYS=1 for cloud library experiments.

Load an example plugin

With Vite or static server:

http://127.0.0.1:3000/plugins/example-coingecko-source.js

Manager → Plugins → Load from URL.

Invariants & edge cases

1. CORS — Flask must allow the Vite origin; Worker pickOrigin allows :3000 and :8081.
2. Pyodide local — needs vendor wheels under public/ (copied to dist on build).
3. Two endpoints — topbar endpoint for engine vs cloud storage plugin config can differ (Flask vs Worker).
4. make prints the Vite URL :3000. Compose serves the built PWA on :8081.

Failure modes

See also

• Build and serve
• Worker local
• Plugin examples