Installation & Setup
The Noma JavaScript SDK is published as @nomacms/js-sdk. It wraps the Content API with typed methods, consistent error handling, and optional project user authentication.
Install
npm install @nomacms/js-sdkCreate a client
import { createClient } from "@nomacms/js-sdk"
const noma = createClient({
projectId: process.env.NOMA_PROJECT_ID!,
apiKey: process.env.NOMA_API_KEY!,
})Use your Project ID from the project dashboard and an API key from User Settings → API Keys. Create the key while the same workspace is active as the project you’re calling (sidebar workspace switcher). Keys are not interchangeable across workspaces—use separate env vars or clients per workspace if needed.
createClient options
| Option | Type | Description |
|---|---|---|
projectId | string | Required. Your project's UUID. |
apiKey | string | API key for CMS routes. Sent as Authorization: Bearer <token> together with the project-id header. |
baseUrl | string | Optional. API base URL. Defaults to https://app.nomacms.com/api (trailing slashes are stripped). |
timeout | number | Optional. Request timeout in milliseconds. Default 30000. |
projectUserAuth | ProjectUserAuthConfig | Optional. End-user session tokens and storage. See Project Auth. |
Environment variables
A typical setup:
NOMA_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NOMA_API_KEY=noma_...Never expose server-side API keys in client bundles. In browsers, use a backend proxy, Edge function, or project user tokens with narrow scopes instead of a full CMS key.
Project metadata
Load project configuration (and optionally nested data) in one call:
const project = await noma.project.get({ with: "collections,fields" })| Param | Description |
|---|---|
with | Optional comma-separated string. Common values include collections, fields. Maps to the API with query parameter. |
See Get Project for the HTTP details.
Project user authentication (optional)
If your app signs in end users (not CMS editors), pass projectUserAuth:
import { createClient } from "@nomacms/js-sdk"
const noma = createClient({
projectId: process.env.NOMA_PROJECT_ID!,
apiKey: process.env.NOMA_API_KEY, // optional if you only call auth routes
projectUserAuth: {
accessToken: storedAccessToken,
refreshToken: storedRefreshToken,
autoRefresh: true,
tokenStorage: myAdapter,
},
})| Field | Description |
|---|---|
accessToken | Current access token after sign-in. |
refreshToken | Refresh token for /auth/refresh. |
autoRefresh | Default true. On 401, the client tries to refresh once before failing. |
tokenStorage | Optional TokenStorageAdapter to persist tokens (see below). |
Auth methods (signUp, signInWithPassword, refreshSession, etc.) live on the same client instance. Full coverage is in the Project Auth docs.
TokenStorageAdapter
Implement this interface to sync tokens with localStorage, cookies, or your own store:
interface TokenStorageAdapter {
getAccessToken(): string | undefined
setAccessToken(token?: string): void
getRefreshToken(): string | undefined
setRefreshToken(token?: string): void
clear(): void
}On construction, if tokenStorage is set, the client reads initial tokens from the adapter.
Debug helper
const info = noma.getDebugInfo()
// { basePath, projectId, timeout, hasApiKey, hasProjectUserToken }Use this for logging or support tickets without printing secrets.
Next steps
- Collections - List, create, update, and delete collections.
- Content - Query and mutate entries.
- Error Handling - Typed errors and
requestInfo.