Skip to content
QGIS SDK

Exports

The root is the import a page needs: QgisSdk, the schema types, the transport client, the error root, the version 1 plugin-description contract and the stores. Everything under ./bridge is also exported from the root; the subpath stays for code that already uses it.

import {
  BridgeClient,
  type BridgeSchema,
  MAX_SAFE_INTEGER,
  MIN_SAFE_INTEGER,
  PLUGIN_DESCRIPTION_SCHEMA_VERSION,
  QgisSdk,
  QgisSdkBridgeRemoteError,
  QgisSdkContractError,
  QgisSdkContractValidationError,
  QgisSdkDeclarationError,
  QgisSdkError,
  QgisSdkValidationIssue,
  QgisSdkWebChannelError,
  createWebChannelTransport,
  defineBridgeSchema,
  insideQgis,
  isSafeJsonInteger,
  parsePluginDescription,
  validateAgainstSchema,
} from "@archont561/qgis-sdk";

  • QgisSdk: QgisSdk.fromBridgeSchema(schema) builds the page’s typed handle on the plugin from its generated schema module, as documented under The schema module and QgisSdk. The same name is the instance type: QgisSdk<Operations, Streams>.

  • Schema types: BridgeSchema<O, S>, OperationsOf<S>, StreamsOf<S> and defineBridgeSchema(...), the one import a generated schema module makes.

  • Default transport: insideQgis() and createWebChannelTransport(objectName) are what QgisSdk uses when no transport is given; a page that builds its own BridgeClient can use them directly instead of hand-writing the QWebChannel glue.

  • Transport client: BridgeClient, its options, frames, the parsers and the seven QgisSdkBridge*Error classes, as documented under Transport client.

  • Safe integer bounds: MAX_SAFE_INTEGER (9007199254740991), MIN_SAFE_INTEGER (-9007199254740991), and isSafeJsonInteger(value) mirror qgis_sdk.models.MAX_SAFE_INTEGER and SafeJsonInteger.

  • Version 1 plugin descriptions: parsePluginDescription(raw) validates and freezes PluginDescription payloads (schema_version: 1) produced by Python’s describe(app).to_json(). qgis-sdk bridge generate is the build-time reader of the same payload; a page only needs this one to render operations it did not generate a client for.

  • Structured SDK errors: every error this package raises extends QgisSdkError and carries a stable wire code ("sdk_error", "invalid_declaration", "contract_validation_failed", "no_web_channel", the transport’s refusal codes, and the code of a remote fault on QgisSdkBridgeRemoteError). Match on the code, not on the class name; a Python-side error such as scope_closed or unsupported_capability reaches a page as a QgisSdkBridgeRemoteError with that code, so the package carries no idle mirror class for it (decision-40).

  • Stores: OperationStore, StreamStore, FormStore/formStore, HostQueryStore/layersQuery/layerFieldsQuery, the Store<T> shape, their state types, schemaFields, labelFor, stableKey and QgisSdkStoreError ("store_error"), as documented under Stores.

What the root does not carry, and why: ./host is generated and large, so it is opt-in; ./react, ./vue and ./svelte each need their optional peer; ./testing is a development dependency. The package exports no internal helper.

Which entry for which page

Section titled “Which entry for which page”
Tier Page Entry points Scaffold (qgis-sdk new --web)
1 Vanilla TypeScript root (QgisSdk + stores) --web vanilla: formStore + layersQuery page
1 React root + ./react --web react: useForm + useHostQuery page
2 Vue 3 root + ./vue none; wire it per Vue bindings
2 Svelte 5 root + ./svelte none; wire it per Svelte bindings

Tier 1 is what the scaffold generates, the opt-in QGIS_SDK_SCAFFOLD_WEB harness builds and QGIS loads in CI. Tier 2 ships the adapter with its own test project and the wiring below, and is covered by the same behaviour suite as the core and the React hooks (tests/store-behaviour.ts); it has no scaffold template (decision-47). Every adapter is one thin subscription layer over the stores: the behaviour lives in the root, so a page can switch framework (or drop it) without changing what the host sees.