TypeScript Support
How to use TypeScript with the starti.app SDK for type-safe development
TypeScript Support
The starti.app SDK is written in TypeScript and ships with full type definitions. You can get autocompletion, type checking, and inline documentation in any TypeScript-aware editor.
Setup
Install the types package
Install the starti.app npm package as a dev dependency. This provides the type definitions — the actual SDK is still loaded from the CDN at runtime.
npm install --save-dev starti.appLoad the SDK from CDN
The SDK itself is loaded via a script tag, not imported as a module. Add it to your HTML <head> as usual:
<script src="https://cdn.starti.app/c/{BRAND_NAME}/main.js"></script>
<link rel="stylesheet" href="https://cdn.starti.app/c/{BRAND_NAME}/main.css" />Use the global startiapp object
Once the npm package is installed, TypeScript recognizes the global startiapp object automatically. The package declares it on window:
// No import needed — the types are globally available after installing the package.
// The global `startiapp` object is typed as `StartiappClass`.
startiapp.addEventListener("ready", async () => {
startiapp.initialize();
const platform = startiapp.App.platform; // type: string
const deviceId = await startiapp.App.deviceId(); // type: string
const volume = await startiapp.Media.getVolume(); // type: number
});Your editor will provide autocompletion for all modules (App, Auth, QrScanner, Media, etc.) and their methods, parameters, and return types.
TypeScript configuration
No special tsconfig.json changes are needed. The package uses the standard types field in package.json to point to its declaration files. As long as the package is installed, the types are picked up automatically.
If you have a restrictive types array in your tsconfig.json, make sure it does not exclude the starti.app package.
Framework examples
React
import { useEffect, useState } from "react";
function DeviceInfo() {
const [platform, setPlatform] = useState<string>("");
useEffect(() => {
async function init() {
try {
await startiapp.initialize();
setPlatform(startiapp.App.platform);
} catch {
// Not running in starti.app container
}
}
init();
}, []);
return <p>Platform: {platform || "web"}</p>;
}Vue 3
<script setup lang="ts">
import { ref, onMounted } from "vue";
const platform = ref("");
onMounted(async () => {
try {
await startiapp.initialize();
platform.value = startiapp.App.platform;
} catch {
// Not running in starti.app container
}
});
</script>
<template>
<p>Platform: {{ platform || "web" }}</p>
</template>Svelte
<script lang="ts">
import { onMount } from "svelte";
let platform = "";
onMount(async () => {
try {
await startiapp.initialize();
platform = startiapp.App.platform;
} catch {
// Not running in starti.app container
}
});
</script>
<p>Platform: {platform || "web"}</p>Available types
The package exports types for all SDK modules. Key types include:
| Type | Description |
|---|---|
StartiappClass | The main SDK class (type of the global startiapp object) |
InitializeParams | Options for startiapp.initialize() |
SetStatusBarOptions | Status bar configuration |
SpinnerOptions | Navigation spinner configuration |
SafeAreaSideOptions | Safe area configuration |
AdvancedSafeAreaOptions | Per-side safe area overrides |
Each module also exports its own types (e.g. QrScannerOptions, VolumeChangedEventArgs). These are available through the type system automatically when you access module methods.
Checking for the container at compile time
Since startiapp is always declared globally by the types package, TypeScript will not warn you if you call SDK methods outside the container. Use isRunningInApp() at runtime to guard native calls:
if (startiapp.isRunningInApp()) {
// Safe to call native methods
const deviceId = await startiapp.App.deviceId();
} else {
// Running in a regular browser
}Or use initialize() with try/catch as shown in the Setup and the Basics guide.