Build

Add account connecting to your site

Put a panel on your own page where your users connect, reconnect and disconnect their social accounts, without your API key ever reaching the browser.

TL;DR

Question	Answer
What are the parts?	A route on your server that makes a connect token, and `<flung-connect>` on the page, which uses it.
What does a person see?	The platforms you offer and their connected accounts, with Connect, Reconnect and Disconnect. Connecting opens the platform's own sign-in in a small window.
Which frameworks?	Any. Next.js, React with Vite and a plain page are shown below, each from a working example.
Can each of my users have their own accounts?	Yes: make each token with that user's `profileId`.

Install

npm install @flung.dev/sdk @flung.dev/connect

Next.js

The server keeps the key, in .env.local:

.env.local

1# A full-access Flung API key (flung_sk_...). Server only: never prefix it with NEXT_PUBLIC_.2FLUNG_API_KEY=3
4# Optional. The API: https://api.flung.dev (the default) or https://api-preview.flung.dev.5FLUNG_BASE_URL=6
7# The origin this app is served from, which connect tokens are made for. http://localhost:3000 when left out.8APP_ORIGIN=

A route makes a connect token for the page. Put your own sign-in check at its top:

app/api/connect-token/route.ts

1import { Flung, FlungError } from '@flung.dev/sdk'2
3/**4 * `POST /api/connect-token`: a short-lived connect token for this app's own page. The API key stays here on the server;5 * the token it makes can only list, connect, reconnect and disconnect accounts, from `APP_ORIGIN`, for fifteen minutes.6 *7 * In a real app, check who is signed in first, and pass their profile as `profileId` so each person sees only theirs.8 */9export async function POST(): Promise<Response> {10  const apiKey = process.env.FLUNG_API_KEY11  if (apiKey === undefined || apiKey === '') return Response.json({ error: 'Set FLUNG_API_KEY in .env.local.' }, { status: 500 })12  const flung = new Flung({ apiKey, ...(process.env.FLUNG_BASE_URL ? { baseUrl: process.env.FLUNG_BASE_URL } : {}) })13  try {14    const { token, expiresAt } = await flung.connectTokens.create({ origins: [process.env.APP_ORIGIN || 'http://localhost:3000'], expiresIn: 900 })15    return Response.json({ token, expiresAt }, { headers: { 'cache-control': 'no-store' } })16  } catch (error) {17    const status = error instanceof FlungError ? (error.status ?? 502) : 50218    return Response.json({ error: error instanceof Error ? error.message : 'Could not make a connect token.' }, { status })19  }20}

The page shows the panel, which asks the route for a token, and again when one expires:

app/accounts.tsx

1'use client'2
3import { useCallback, useState } from 'react'4
5import { FlungConnect } from '@flung.dev/connect/react'6
7/** Asks this app's server for a connect token; the panel calls it again when a token expires. */8async function connectToken(): Promise<string> {9  const response = await fetch('/api/connect-token', { method: 'POST' })10  const body = (await response.json()) as { token?: string; error?: string }11  if (!response.ok || body.token === undefined) throw new Error(body.error ?? 'Could not make a connect token.')12  return body.token13}14
15export function Accounts({ baseUrl }: { baseUrl: string | undefined }) {16  const [events, setEvents] = useState<string[]>([])17  const log = useCallback((line: string) => setEvents((previous) => [line, ...previous].slice(0, 5)), [])18  return (19    <>20      <FlungConnect21        token={connectToken}22        baseUrl={baseUrl}23        onConnect={({ accounts }) => log(`Connected ${accounts.map((account) => account.username ?? account.id).join(', ')}`)}24        onDisconnect={({ account }) => log(`Disconnected ${account.username ?? account.id}`)}25        onError={({ code, message }) => log(`${code}: ${message}`)}26      />27      {events.length > 0 && (28        <ul className="events" aria-label="What happened">29          {events.map((line, index) => (30            <li key={`${index}-${line}`}>{line}</li>31          ))}32        </ul>33      )}34    </>35  )36}

React with Vite

For trying the panel out, Vite's development server can make the token itself:

vite.config.ts

1import { Flung } from '@flung.dev/sdk'2import { defineConfig, loadEnv } from 'vite'3import type { Connect, Plugin } from 'vite'4
5/**6 * `POST /connect-token` on the dev and preview servers: makes a connect token for the page with the key from7 * `.env.local`. The key has no `VITE_` prefix, so Vite never puts it in the bundle. This is for trying the panel out; a8 * deployed app makes tokens on its own server, behind its own sign-in.9 */10function connectTokens(apiKey: string, baseUrl: string | undefined): Plugin {11  const handler: Connect.NextHandleFunction = (request, response, next) => {12    if (request.method !== 'POST' || request.url !== '/connect-token') return next()13    const send = (status: number, body: unknown) => {14      response.statusCode = status15      response.setHeader('content-type', 'application/json')16      response.setHeader('cache-control', 'no-store')17      response.end(JSON.stringify(body))18    }19    if (apiKey === '') return send(500, { error: 'Set FLUNG_API_KEY in .env.local.' })20    const origin = request.headers.origin ?? `http://${request.headers.host ?? 'localhost:5173'}`21    const flung = new Flung({ apiKey, ...(baseUrl ? { baseUrl } : {}) })22    flung.connectTokens.create({ origins: [origin], expiresIn: 900 }).then(23      ({ token }) => send(200, { token }),24      (error: unknown) => send(502, { error: error instanceof Error ? error.message : 'Could not make a connect token.' }),25    )26  }27  return { name: 'flung-connect-tokens', configureServer: (server) => void server.middlewares.use(handler), configurePreviewServer: (server) => void server.middlewares.use(handler) }28}29
30export default defineConfig(({ mode }) => {31  const env = loadEnv(mode, process.cwd(), '')32  return {33    plugins: [connectTokens(env.FLUNG_API_KEY ?? '', env.FLUNG_BASE_URL || undefined)],34    define: { 'import.meta.env.FLUNG_BASE_URL': JSON.stringify(env.FLUNG_BASE_URL || '') },35    esbuild: { jsx: 'automatic' },36  }37})

src/App.tsx

1import { useCallback, useState } from 'react'2
3import { FlungConnect } from '@flung.dev/connect/react'4
5/** Asks the dev server for a connect token; the panel calls it again when a token expires. */6async function connectToken(): Promise<string> {7  const response = await fetch('/connect-token', { method: 'POST' })8  const body = (await response.json()) as { token?: string; error?: string }9  if (!response.ok || body.token === undefined) throw new Error(body.error ?? 'Could not make a connect token.')10  return body.token11}12
13const baseUrl = import.meta.env.FLUNG_BASE_URL || undefined14
15export function App() {16  const [events, setEvents] = useState<string[]>([])17  const log = useCallback((line: string) => setEvents((previous) => [line, ...previous].slice(0, 5)), [])18  return (19    <main>20      <h1>Connect your accounts</h1>21      <p>We post to the accounts you connect here. You can disconnect them at any time.</p>22      <FlungConnect23        token={connectToken}24        baseUrl={baseUrl}25        onConnect={({ accounts }) => log(`Connected ${accounts.map((account) => account.username ?? account.id).join(', ')}`)}26        onDisconnect={({ account }) => log(`Disconnected ${account.username ?? account.id}`)}27        onError={({ code, message }) => log(`${code}: ${message}`)}28      />29      {events.length > 0 && (30        <ul className="events" aria-label="What happened">31          {events.map((line, index) => (32            <li key={`${index}-${line}`}>{line}</li>33          ))}34        </ul>35      )}36    </main>37  )38}

A deployed app makes tokens on its own server, behind its own sign-in, as the Next.js route does.

A plain page

No framework and nothing to install: a server of a few lines makes the token, and the page loads the panel.

server.mjs

1#!/usr/bin/env node2/**3 * The smallest server a connect panel needs, with nothing to install: it keeps the API key, makes a connect token for4 * the page when the page asks, and serves the page and the built package.5 *6 *   pnpm build7 *   FLUNG_API_KEY=flung_sk_... node examples/vanilla/server.mjs8 *9 * Then open http://localhost:5173. FLUNG_BASE_URL=https://api-preview.flung.dev tries it against preview.10 */11import { readFile } from 'node:fs/promises'12import { createServer } from 'node:http'13import { extname, join, normalize } from 'node:path'14
15const PORT = Number(process.env.PORT ?? 5173)16const ORIGIN = `http://localhost:${PORT}`17const BASE_URL = process.env.FLUNG_BASE_URL ?? 'https://api.flung.dev'18const API_KEY = process.env.FLUNG_API_KEY19if (API_KEY === undefined) throw new Error('Set FLUNG_API_KEY to a full-access Flung API key.')20
21const here = import.meta.dirname22const dist = join(here, '..', '..', 'packages', 'connect', 'dist')23const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8' }24
25/** In your app, check who is signed in here first, and pass their profile as `profileId`. */26async function connectToken() {27  const response = await fetch(`${BASE_URL}/v1/connect-tokens`, {28    method: 'POST',29    headers: { authorization: `Bearer ${API_KEY}`, 'content-type': 'application/json' },30    body: JSON.stringify({ origins: [ORIGIN], expiresIn: 900 }),31  })32  return { status: response.status, body: await response.text() }33}34
35createServer(async (request, response) => {36  const path = new URL(request.url ?? '/', ORIGIN).pathname37  if (request.method === 'POST' && path === '/connect-token') {38    const made = await connectToken()39    response.writeHead(made.status, { 'content-type': 'application/json' }).end(made.body)40    return41  }42  const file = path === '/' ? join(here, 'index.html') : path.startsWith('/connect/') ? normalize(join(dist, path.slice('/connect/'.length))) : null43  if (file === null || (file !== join(here, 'index.html') && !file.startsWith(dist))) {44    response.writeHead(404).end()45    return46  }47  try {48    const page = file.endsWith('index.html') ? (await readFile(file, 'utf8')).replace('__FLUNG_BASE_URL__', BASE_URL) : await readFile(file)49    response.writeHead(200, { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream' }).end(page)50  } catch {51    response.writeHead(404).end()52  }53}).listen(PORT, () => process.stdout.write(`Open ${ORIGIN}\n`))

index.html

1<!doctype html>2<html lang="en">3  <head>4    <meta charset="utf-8">5    <meta name="viewport" content="width=device-width, initial-scale=1">6    <title>Connect your accounts</title>7    <style>8      body { font: 16px/1.5 system-ui, sans-serif; max-width: 36rem; margin: 8vh auto; padding: 0 16px; }9      @media (prefers-color-scheme: dark) { body { background: #09090b; color: #f4f4f5; } }10      pre { font-size: 13px; overflow: auto; }11    </style>12  </head>13  <body>14    <h1>Connect your accounts</h1>15    <p>Flung posts to the accounts you connect here. You can disconnect them at any time.</p>16    <flung-connect id="panel" base-url="__FLUNG_BASE_URL__"></flung-connect>17    <pre id="log"></pre>18    <script type="module">19      import '/connect/register.js'20
21      const panel = document.getElementById('panel')22      const log = (type, detail) => (document.getElementById('log').textContent += `${type} ${JSON.stringify(detail)}\n`)23      // A function, so the panel asks for a fresh token when one expires.24      panel.token = async () => {25        const response = await fetch('/connect-token', { method: 'POST' })26        if (!response.ok) throw new Error(`Could not make a connect token: ${await response.text()}`)27        return (await response.json()).token28      }29      for (const type of ['flung-connect', 'flung-disconnect', 'flung-error']) panel.addEventListener(type, (event) => log(type, event.detail))30    </script>31  </body>32</html>

How it behaves

The panel offers only the platforms this Flung can connect, narrowed by its platforms attribute and the token's own list.
Connecting opens the platform's sign-in in a small window. When a browser blocks the window, the panel shows a link instead.
Mastodon asks for the person's server first; Bluesky takes a handle when they have one.
Disconnecting asks to confirm. The account then leaves the panel.
With mode="redirect" the whole page goes to the platform and back, for pages that cannot open windows.

Every attribute, event, style hook and word is in the connect panel reference.