Intent View
A live view in Axil Studio of whether the running app keeps the contracts its decorators declare - intent mode, violations, SLOs, circuit breakers and enforced decorators - set up with intentEndpoint().
On this page8
The Intent view shows, live, whether the running app keeps the contracts declared by its decorators. It reads the report that @axiljs/runtime publishes and refreshes every 2 seconds while the view is open.
Note
New in 0.3.5. Open it from the sidebar (Tools group), the command palette, or with g i.
What it shows
- Header: the intent mode as a badge (
enforce,warnoroff), where the report came from (in-processorfrom app), when it was last updated, and a Refresh button. - Summary cards: the number of violations with the time and decorator of the last one, how many SLOs are meeting their objective, how many circuits are tracked and how many are open or half-open, and how many decorators are enforced. A card is highlighted when something needs attention.
- Violations: newest first, with time, decorator, target, detail, request ID and tenant ID. The newest 200 are shown; the runtime keeps up to 500.
- Service level objectives: one row per
tSlomethod with the percentile, observed and target latency, error rate and error budget, the number of samples, and the status (meeting, orbreachingwithlatency,errorsor both). A method appears after its first call. - Circuit breakers: every
tCircuitBreakermethod with its state (closed,open,half-open). A method appears after its first call. - Enforced decorators: every registered interceptor with its order, outermost first.
Polling pauses while the browser tab is hidden and resumes when it becomes visible again. If a refresh fails after data has been shown, the last data stays on screen with a "Live updates paused" notice.
Setup
Under axil run your app runs in a child process, so Studio cannot read the runtime's state directly. The app has to serve its report on a development-only endpoint:
1import '@axiljs/runtime'
2import { wire } from '@axiljs/runtime'
3import { intentEndpoint } from '@axiljs/studio'
4
5wire(OrderService) // executes the t* decorators on its methods
6app.use(intentEndpoint()) // serves GET /__axil/studio/intent to StudioUntil the endpoint is reachable, the view shows "Intent reporting is not enabled" with the reason and this snippet, ready to copy.
intentEndpoint(options?)
| Option | Default | Description |
|---|---|---|
path | /__axil/studio/intent | Path to answer on. Studio's intentPath setting must match |
enabled | NODE_ENV !== 'production' | Serve the report; when disabled the handler does nothing |
The endpoint is safe to leave in the code:
- It answers only
GETandHEADon its path. - It answers only requests from a loopback address (
127.x.x.x,::1). - It is a no-op when
NODE_ENVisproduction, unless you passenabled: true. - Every other request goes to
next().
It works as AxilJS middleware (app.use(intentEndpoint())) and as a plain node:http handler, where it returns true when it answered the request.
Keeping Studio a dev dependency
@axiljs/studio is usually a devDependency, so a production install with npm ci --omit=dev does not have it. The endpoint lives in a module with no imports, @axiljs/studio/dist/intent, which can be loaded on its own behind a development check. The saas-api and high-scale-api templates (0.3.6) do it this way in src/dev/studio-intent.ts:
1import { createRequire } from 'node:module'
2import type { MiddlewareFn } from '@axiljs/core'
3
4export function studioIntentEndpoint(): MiddlewareFn | undefined {
5 if (process.env.NODE_ENV !== 'production') {
6 try {
7 const require = createRequire(import.meta.url)
8 const studio = require('@axiljs/studio/dist/intent') as { intentEndpoint(): MiddlewareFn }
9 return studio.intentEndpoint()
10 } catch {
11 // Studio is not installed (dev dependencies omitted): nothing to serve
12 }
13 }
14 return undefined
15}const intent = studioIntentEndpoint()
if (intent) app.use(intent)Data flow
@axiljs/runtimepublishesruntimeReport()onglobalThis[Symbol.for('axiljs.runtime.report')]. Studio never imports the runtime.- The browser polls
GET /api/studio/intenton the Studio server. - If the runtime is loaded in Studio's own process (Studio started programmatically inside the app), Studio reads the report directly and no endpoint is needed.
- Otherwise Studio requests
http://localhost:<appPort>plusintentPathfrom the app, with a 1.5 second timeout.
GET /api/studio/intent
Returns the report with available: true:
1{
2 "available": true,
3 "source": "app",
4 "mode": "enforce",
5 "enforced": [{ "decorator": "tDeprecated", "order": 50 }, { "decorator": "tSlo", "order": 60 }],
6 "violations": [
7 {
8 "decorator": "tTenantIsolated",
9 "target": "Invoices.list",
10 "detail": "returned data of tenant 'globex' to tenant 'acme'",
11 "requestId": "8f9b6c1e-4c1d-4c8e-9a51-2a7d3f0b6e11",
12 "tenantId": "acme",
13 "timestamp": "2026-11-17T10:15:00.000Z"
14 }
15 ],
16 "slo": [],
17 "circuits": { "Pricing.price": "CLOSED" },
18 "generatedAt": "2026-11-17T10:15:02.000Z"
19}or { "available": false, "reason": "..." }. The reason tells you what to fix:
| Reason | Cause |
|---|---|
The app does not serve /__axil/studio/intent. Add app.use(intentEndpoint()) from @axiljs/studio in development. | The app answered 404 |
Could not reach the app at http://localhost:3000. Is it running? | The app is not running or not on the expected port |
The app at http://localhost:3000 did not answer /__axil/studio/intent within 1.5 s | The request timed out |
@axiljs/runtime is not loaded in this process. ... | The endpoint answered, but the app never imported @axiljs/runtime |
The app answered /__axil/studio/intent with HTTP 403 (or another status) | Something in front of the endpoint refused the request |
Warning
If middleware registered before intentEndpoint() answers or rejects the request (for example authentication applied to every route), Studio receives that response instead of the report. Register the endpoint before such middleware.
Configuration
When Studio is started programmatically, the intentPath option sets the path it requests from the app (default /__axil/studio/intent). It must match intentEndpoint({ path }). See Configuration.
Related
- Intent verification: what the runtime checks and records
- Resilience: circuit breakers and the interceptor order
axil verify: the same contracts, checked in your test suite- Keyboard shortcuts
- HTTP API
Was this page helpful?