Reference
packlets.js, packlets.css, session token
Everything for your app's page: the bridge, the stylesheet and the token.
Reference for the page of your app: the packlets.js bridge, the session token, and the packlets.css stylesheet.
packlets.js
<script src="https://packlets.app/embed/packlets.js"></script>After that, the packlets object is available:
| Call | Result |
|---|---|
packlets.inPacklets | true if the page runs in the Packlets app, otherwise false. Not a call, but a value. |
packlets.launch | Launch data, available immediately on load: { v, packlet_id, platform, theme, locale }. Not a call, but a value. |
packlets.locale | Language of the app: "de" or "en" (see Language). Not a call, but a value. |
packlets.theme | The colors of Packlets (see Colors). Not a call, but a value. |
packlets.ready() | Reports that the page is ready. Packlets then hides the placeholder. Only needed with data-ready="manual". |
await packlets.token() | The session token as text. Right after loading, it comes from the launch data without any wait. |
await packlets.fetch(url, init) | Like fetch(), but sets Authorization: Bearer <token> with a fresh token. Returns the normal response. |
await packlets.info() | { app: "packlets", version: 2, packlet_id: "…", platform: "iOS", theme: {…}, locale: "en" }. platform is iOS or android, locale is de or en. |
packlets.toast("Saved") | Short message in the app. The text is cut off after 140 characters. |
packlets.open("https://…") | Opens the address in the phone's browser. http(s) only. |
packlets.haptic("success") | Vibration: tap (default), selection, success, or error. |
await packlets.storage.get(key) | Stored text or null. See Storage. |
await packlets.storage.set(key, text) | Stores text (up to 16 KB). |
await packlets.storage.remove(key) | Deletes an entry. |
await packlets.storage.keys() | All keys of this app. |
All calls except the values (packlets.inPacklets, packlets.launch, packlets.locale, packlets.theme) return a promise.
- Outside Packlets (for example in a browser), the calls fail immediately. So check
packlets.inPackletsfirst. - Timeout: If the app doesn't respond within 15 seconds, the call fails.
- Your address only: Only pages with the same origin (
https, host, and port) as the address you set aspageget responses. - Main page only: Every call carries a secret bridge key from the launch data. Calls from iframes of other addresses don't have it, and Packlets ignores them. More under iframes and external content.
- When the page runs in Packlets,
<html>has the classin-packlets. Once the script has loaded, thepacklets:readyevent fires onwindow. - Reopened: Packlets keeps the most recently opened pages in memory (up to four). When someone comes back, the page doesn't reload. Instead, the
packlets:activatedevent fires onwindow. That is the right moment to refresh stale data. The button at the top right next to the bell reloads the page completely if needed.
Loading and placeholder
Until your page is ready, Packlets shows the avatar and name of the app. Normally the placeholder disappears as soon as the page has loaded. If your page still loads data afterwards, include the script with data-ready="manual" and call packlets.ready() yourself when everything is in place. If no ready() arrives after six seconds, Packlets hides the placeholder anyway.
<script src="https://packlets.app/embed/packlets.js" data-ready="manual"></script>
<script>
loadEverything().then(() => packlets.ready());
</script>Launch data
When loading, Packlets appends launch data to the address, after #packlets= (Base64url-encoded JSON). The part after # never goes to your server. packlets.js reads it immediately, exposes it as packlets.launch, and removes it from the address again. For the first 45 seconds, packlets.token() returns the session token from the launch data without a detour through the app. That way, your page knows who is opening it on the very first call to your server (like initData in Telegram).
packlets.js stores the bridge key from the launch data in the sessionStorage of your address. That way, packlets also works on other pages you link to within your address. You don't have to do anything for this.
Language
Packlets is available in German and English, depending on the phone's language. This language is in the launch data as locale ("de" or "en"), in packlets.info(), and as packlets.locale. Outside Packlets, packlets.locale uses the browser's language: de for German, otherwise en. If <html> has no lang yet, packlets.js sets it to this value.
const text = packlets.locale === "de" ? { save: "Speichern" } : { save: "Save" };
document.querySelector("#save").textContent = text.save;
const date = new Intl.DateTimeFormat(packlets.locale, { dateStyle: "medium" }).format(new Date());If your server builds texts itself, the Accept-Language header helps: Packlets sends it when loading the page, in the language of the app.
Colors
packlets.theme contains the colors of Packlets: bg, surface, text, text_secondary, text_tertiary, field, cta, on_cta, danger, and scheme (light). packlets.js also sets them as CSS variables on <html>, for example --packlets-bg, --packlets-text, --packlets-cta, or --packlets-text-secondary. That way, your page fits the app without any colors of its own.
Spacing
In Packlets, your page fills the whole area below Packlets' slim header down to the bottom edge (full screen). The header always stays the same and covers nothing. At the bottom, Packlets sets the CSS variable --packlets-inset-bottom (the iPhone's home bar) and gives <html> this spacing as padding; --packlets-inset-top still exists but is 0. Normally you don't have to do anything.
- If you want to fill the full height without scrolling, subtract the insets:
min-height: calc(100vh - var(--packlets-inset-top) - var(--packlets-inset-bottom)). - If you want to handle everything yourself, write
<html data-packlets-insets="manual">and use the variables where appropriate.
Storage
packlets.storage stores small texts on the device, separated by account and app. If two accounts share a phone, neither sees the other's entries. That sets it apart from the page's normal localStorage. Up to 100 entries per app, each up to 16 KB. For objects, use JSON.stringify and JSON.parse. When someone signs out, the entries stay on the device. If they delete their account, the entries are worthless, because nobody else can read them.
Session token
A JWT that says who is currently opening the page in Packlets.
| Algorithm | HS256 |
| Secret | SHA-256 hash of your key as lowercase hex text. The same as for the webhook signature. |
| Validity | 60 seconds |
| Field | Content |
|---|---|
iss | https://api.packlets.app |
aud | ID of your packlet. The same as packlet_id in every webhook event. |
sub | ID of the user in Packlets. Always stays the same for the same user. |
email | The user's email address. |
name | The user's name, may be missing. |
iat, exp | Issued at and valid until, as Unix time. |
jti | Unique identifier of this token. |
On your server, always check three things: the signature, exp, and that aud is your packlet. If you generate a new key in the app, all tokens become invalid immediately.
Let Packlets verify the token
Without a JWT library of your own, your server asks Packlets. This call needs no key.
POST https://api.packlets.app/v1/session-token/verify
Content-Type: application/json| Field | Type | Required | Meaning |
|---|---|---|---|
token | text | yes | The token from the Authorization header of the request to your server. |
Response for a valid token:
{
"valid": true,
"packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
"page_url": "https://your-site.example/app",
"user": { "id": "4f1c…", "email": "[email protected]", "name": "You" },
"expires_at": "2026-11-10T08:16:00.000Z"
}Otherwise status 401:
{ "valid": false, "error": "invalid_token", "message": "The token is invalid or has expired." }Careful: Compare packlet_id with the ID of your packlet. Otherwise your server also accepts tokens that were issued for someone else's packlet. If your server serves many packlets (for example one app for all users), check page_url instead: that is the page the packlet is currently showing.
The rate limit applies to this call, counted per address of your server.
packlets.css
<link rel="stylesheet" href="https://packlets.app/embed/packlets.css">The stylesheet brings the Lato font, the app's colors, and these building blocks:
| Class | Used for |
|---|---|
packlets | Frame of the page: 16 pixels of padding, blocks stacked with 12 pixels of spacing, at least as tall as the screen. |
packlets-title, packlets-big | Heading (20 px) and large number (44 px). |
packlets-sub, packlets-label, packlets-note | Gray secondary text, section label in capitals, small note. |
packlets-row, packlets-spread, packlets-grow, packlets-push | Side by side; spread to the edges; fill space; push to the bottom. |
packlets-button | Button like in the app, 44 px tall. Plus is-secondary (light) and is-small (32 px). |
packlets-tabs | Switcher between views. The active tab carries aria-selected="true". |
packlets-list | List with fine divider lines, rows at least 44 px tall. |
packlets-table | Table. Number columns right-aligned with is-num. |
packlets-field | Input field. |
packlets-chip, packlets-dot | Small badge; status dot green, red with is-warn. |
packlets-bars | Small bar chart made of <i style="height: 40%">. The active bar carries is-active. |
Colors and sizes as variables:
| Variable | Meaning |
|---|---|
--packlets-bg | Background |
--packlets-text, --packlets-text-2, --packlets-text-3 | Main text, secondary text, even lighter text |
--packlets-icon | Icons |
--packlets-cta, --packlets-on-cta | Dark blue of the buttons and the text on them |
--packlets-field | Light gray for fields and light buttons |
--packlets-selected, --packlets-bar | Selected tab, bars in the chart |
--packlets-divider | Divider lines |
--packlets-ok, --packlets-warn | Green and red for status |
--packlets-radius | Corner radius |
Text can't be selected on the page (user-select: none), like in an app. A finished example page is at /embed/beispiel.html.