Reference

packlets.js, packlets.css, session token

Everything for your app's page: the bridge, the stylesheet and the token.

Open as Markdown

Reference for the page of your app: the packlets.js bridge, the session token, and the packlets.css stylesheet.

packlets.js

html
<script src="https://packlets.app/embed/packlets.js"></script>

After that, the packlets object is available:

CallResult
packlets.inPackletstrue if the page runs in the Packlets app, otherwise false. Not a call, but a value.
packlets.launchLaunch data, available immediately on load: { v, packlet_id, platform, theme, locale }. Not a call, but a value.
packlets.localeLanguage of the app: "de" or "en" (see Language). Not a call, but a value.
packlets.themeThe 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.inPacklets first.
  • 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 as page get 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 class in-packlets. Once the script has loaded, the packlets:ready event fires on window.
  • 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:activated event fires on window. 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.

html
<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.

js
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.

AlgorithmHS256
SecretSHA-256 hash of your key as lowercase hex text. The same as for the webhook signature.
Validity60 seconds
FieldContent
isshttps://api.packlets.app
audID of your packlet. The same as packlet_id in every webhook event.
subID of the user in Packlets. Always stays the same for the same user.
emailThe user's email address.
nameThe user's name, may be missing.
iat, expIssued at and valid until, as Unix time.
jtiUnique 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.

HTTP
POST https://api.packlets.app/v1/session-token/verify
Content-Type: application/json
FieldTypeRequiredMeaning
tokentextyesThe token from the Authorization header of the request to your server.

Response for a valid token:

JSON
{
  "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:

JSON
{ "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

html
<link rel="stylesheet" href="https://packlets.app/embed/packlets.css">

The stylesheet brings the Lato font, the app's colors, and these building blocks:

ClassUsed for
packletsFrame of the page: 16 pixels of padding, blocks stacked with 12 pixels of spacing, at least as tall as the screen.
packlets-title, packlets-bigHeading (20 px) and large number (44 px).
packlets-sub, packlets-label, packlets-noteGray secondary text, section label in capitals, small note.
packlets-row, packlets-spread, packlets-grow, packlets-pushSide by side; spread to the edges; fill space; push to the bottom.
packlets-buttonButton like in the app, 44 px tall. Plus is-secondary (light) and is-small (32 px).
packlets-tabsSwitcher between views. The active tab carries aria-selected="true".
packlets-listList with fine divider lines, rows at least 44 px tall.
packlets-tableTable. Number columns right-aligned with is-num.
packlets-fieldInput field.
packlets-chip, packlets-dotSmall badge; status dot green, red with is-warn.
packlets-barsSmall bar chart made of <i style="height: 40%">. The active bar carries is-active.

Colors and sizes as variables:

VariableMeaning
--packlets-bgBackground
--packlets-text, --packlets-text-2, --packlets-text-3Main text, secondary text, even lighter text
--packlets-iconIcons
--packlets-cta, --packlets-on-ctaDark blue of the buttons and the text on them
--packlets-fieldLight gray for fields and light buttons
--packlets-selected, --packlets-barSelected tab, bars in the chart
--packlets-dividerDivider lines
--packlets-ok, --packlets-warnGreen and red for status
--packlets-radiusCorner 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.