Skip to main content

Browser vs server

@tenantcloud/sdk ships two builds with one type surface:

BuildSelected byTalks toIdentity
Browser (@tenantcloud/sdk/browser)The browser export condition (Vite, webpack, any bundler)Your app's own origin under /_tc/*The Edge session cookie (same-origin requests)
Server (@tenantcloud/sdk/server)The node export conditionPlatform services via injected env varsThe X-TC-User header on the incoming request, or the project token in jobs

You can import a build explicitly with @tenantcloud/sdk/browser or @tenantcloud/sdk/server.

The /_tc/* paths​

Every project origin (https://<project>.apps.<your-domain>) serves the platform under /_tc/:

PathWhat
/_tc/auth/meThe signed-in user (JSON)
/_tc/auth/login?rd=…, /_tc/auth/logoutSign-in round trip, single sign-out
/_tc/db/*The project's Data API (PostgREST)
/_tc/storage/v1/*File storage
/_tc/int/<integration>/*The Integration Gateway

The browser build only ever calls these same-origin paths, so there is nothing to configure and no CORS.

Member availability​

MemberBrowserServer
tc.auth.user()Yes (calls /_tc/auth/me)Yes, tc.auth.user(req) verifies X-TC-User
tc.auth.token()Returns nullYes
tc.auth.login(), tc.auth.logout()YesNo
tc.db.from(), tc.db.rpc()YesYes, as the current request's user
tc.db.sqlThrows SERVER_ONLYYes (service role)
tc.db.asUser(req), tc.db.pool()Throws SERVER_ONLYYes
tc.db.end()No-opCloses the pool
tc.storageYesYes
tc.m365, tc.int, tc.teamsYesYes
tc.int.<name>.connect(), .status(), .disconnect()YesNo
tc.middleware()Throws SERVER_ONLYYes
tc.withRequest(req, fn)Runs fn()Yes

Server environment​

On the server the SDK reads these variables. The platform sets all of them; you never set them yourself (names starting with TC_ are reserved).

VariableUsed by
DATABASE_URLtc.db.sql, tc.db.pool() (service role)
TC_POSTGREST_URLtc.db.from(), tc.db.asUser()
TC_GATEWAY_URLtc.m365, tc.int, tc.teams
TC_STORAGE_URLtc.storage
TC_JWKS_URLVerifying X-TC-User
TC_PROJECTThe expected token audience (tc:app:<project>)
TC_PROJECT_URLAbsolute signed and public storage URLs
TC_PROJECT_TOKENCron and worker services only: the app's own identity
TC_PROJECT_OWNER_EMAILMail sent as the app
TC_DB_POOLOptional: database pool size (default 5)
PORTWhere your app listens (8080)

If one is missing (for example when you run the server outside the platform), the call throws NOT_CONFIGURED with a fix that tells you to deploy.

createClient(options)​

Apps use the default tc export. createClient exists for tests and scripts.

createClient(opts?: { origin?: string; fetch?: typeof fetch; env?: Record<string, string | undefined> }): Tc
OptionBuildDescription
originBrowserThe app origin to call (default location.origin)
fetchBothA custom fetch (tests)
envServerEnvironment to read instead of process.env
test/setup.js
import { createClient } from '@tenantcloud/sdk/server'

const tc = createClient({ env: { TC_JWKS_URL: 'http://localhost:9999/jwks', TC_PROJECT: 'expenses' } })

Helpers​

ExportDescription
userToken(req)Server build only. Pulls the raw X-TC-User token from an Express/Node request, a Fetch Request, a Hono context or a string
rowsToObjects(values)Turns [[header…], [row…]] into objects keyed by the header row. Empty headers become column_<n>
shareId(url)The Microsoft Graph "shares" key for a SharePoint/OneDrive URL
Was this page helpful?