Local development

The dev-server (@i99dash/sdk-dev-server, invoked via sdk-i99dash dev) simulates the i99dash host so your mini-app's code paths run unchanged. No if (dev) branches in your app.

sdk.config.json

{
  "appRoot": "./src",
  "distDir": "./dist",
  "mocksDir": "./mocks",
  "dev": {
    "port": 5173,
    "host": "127.0.0.1",
    "context": {
      "userId": "u-dev",
      "activeCarId": "VIN-DEV-0001",
      "locale": "en",
      "isDark": false
    }
  }
}

Every field has a sensible default; the file is optional.

Fixture grammar

mocks/fuel-stations.GET.json:

{
  "match": { "path": "/api/v1/fuel-stations", "method": "GET" },
  "response": {
    "success": true,
    "data": {
      "stations": [{ "name": "Shell", "price_sar": 2.33 }]
    }
  }
}

To simulate an error:

{
  "match": { "path": "/api/v1/fuel-stations", "method": "GET", "query": { "simulate": "offline" } },
  "response": {
    "success": false,
    "error": { "code": "NETWORK_ERROR", "message": "simulated" }
  }
}

Matching rules (first filename alphabetically wins):

1. path exact.
2. method exact.
3. If query is present, every declared key/value must appear in the incoming request's query. Extra keys in the request are fine; missing keys are a miss.

Missing fixture → {success: false, error: {code: 'NO_FIXTURE', ...}} so you always see gaps loudly during development.

Fixtures hot-reload on save.

Control panel

http://127.0.0.1:5173/_sdk/ui:

Toggle:

• Driving (off = 0 km/h, on = 40 km/h; exercises the real host's safety gate).
• VIN (free-form text).
• Locale (ar / en — flips text direction in the SDK's host context).
• Theme (light / dark — matches the host's isDark field).

All changes are live — the shim reads state from the dev-server, so calling getContext again returns the latest values.

Gotchas

Running your framework's own dev-server alongside

You can skip sdk-i99dash dev and run your framework's native dev server (e.g. next dev) — the catch is that the host bridge isn't attached. Two workarounds:

1. Add a <script src="http://127.0.0.1:5173/_sdk/bridge.js"> tag to your framework's document head during dev. Run both servers simultaneously; the shim attaches the host bridge so the SDK works.
2. Use sdk-i99dash dev in front as the primary and point it at your framework's build output via appRoot — works for static exports.