SDK Overview - Edpire

@edpire/sdk is the embeddable SDK for delivering, rendering and grading Edpire assessments from your own application. It is one npm package with four entry points. Pick the ones your integration needs.

New here? Two ways to ship covers the two shapes an integration can take and which one you want, before you touch any of this.

The four entry points

Import	Runs in	Use it for
`@edpire/sdk`	Browser	Embedded Player (`EdpireAssessment.mount()`) and Custom Flow helpers (`flattenAssessment`, `renderQuestion`, `buildSubmitPayload`).
`@edpire/sdk/react`	Browser (React 18 or 19)	React components: `EdpireAssessmentPlayer` (drop-in player), `AssessmentShell` (bring your own data), `EdpireQuestion` (single question for Custom Flow).
`@edpire/sdk/core`	Anywhere	`flattenAssessment` and `buildSubmitPayload` with no React, no DOM, no styles. Import these from a route handler or any server file.
`@edpire/sdk/client`	Node.js (18+)	Server client (`EdpireClient`): list assessments, mint embed tokens, submit, check, manage webhooks. API key never leaves the server.

import { EdpireAssessment, flattenAssessment } from "@edpire/sdk"          // browser
import { EdpireAssessmentPlayer, EdpireQuestion } from "@edpire/sdk/react" // React
import { buildSubmitPayload } from "@edpire/sdk/core"                      // server-safe
import { EdpireClient } from "@edpire/sdk/client"                          // server

Import the pure helpers from @edpire/sdk/core, not @edpire/sdk, in any server file. The main entry pulls in React and the whole player tree at module load, which a server bundle cannot take. /core is the same functions with none of that.

For a plain <script> tag or a mobile WebView, use the UMD build instead. See Embedded Player and Mobile.

Starter templates

The fastest way to get running. Both examples ship inside the @edpire/sdk npm package:

# Next.js App Router
npx --package=@edpire/sdk create-edpire-app nextjs my-app

# Vite + Express (works in dev and production)
npx --package=@edpire/sdk create-edpire-app vite-express my-app

Both use createEdpireTokenHandler + <EdpireAssessmentPlayer> and include a README with a cp .env.example .env → npm install → npm run dev quickstart.

Installation

The SDK is published to the public npm registry, so no auth token or .npmrc setup is required.

npm install @edpire/sdk
# or: pnpm add @edpire/sdk

Peer dependencies: react@^18 || ^19 and react-dom@^18 || ^19, required only if you use @edpire/sdk in the browser or @edpire/sdk/react. The /client and /core entries have zero browser dependencies.

Cannot run the npm package, whether that is Flutter, native iOS or Android, React 17 or older, or a strict no-bundler page? Load the UMD build from a CDN and use the EdpireSDK global. Nothing to install, and it carries its own React inside a closure so your framework does not matter. See Embedded Player and Mobile.

Licensing & security

The package is public and free to install, but it carries a proprietary license: you may use it to integrate with Edpire, not to redistribute it or build a competing product. See the LICENSE in the package. Being public is safe because the SDK is not Edpire’s security boundary. The server is. The published bundle contains only the question renderer. It never includes:

Answer keys, stripped from every client-facing payload.
Grading logic, which runs server-side. The SDK does not ship it.
API keys, which stay on your server. The browser only ever holds a short-lived, single-use, origin-scoped embed token.

So even though the JavaScript is readable (as all frontend code is), it grants no access to content, scoring, or your account. See Security for the full model.

CSS

The SDK bundles all its styles into its JavaScript and injects them on first render. You normally do not import any CSS.

Path	Behaviour
Embedded Player (`EdpireAssessment.mount()`)	Fully automatic. Nothing to import.
React components (`AssessmentShell`, `EdpireQuestion`)	Automatic. `shell.css` is imported by the components themselves.
Custom Flow, styles missing	Only if inline-style injection is blocked (sandboxed iframe, strict CSP), import the fallback explicitly: `import "@edpire/sdk/styles/runtime-utilities.css"`.

Math rendering (KaTeX) and feedback states ship with the components, so you do not need to import KaTeX CSS separately when using the SDK. That is only required when integrating the raw @youssefalmia/* runtime packages directly.

Next steps

Embedded Player

Drop the full assessment player into your page with one function call.

Custom Flow

Build a Duolingo-style, question-by-question experience.

Branding

Logo, colors, fonts, and the grading overlay.

Server client

Every EdpireClient method, typed.

​The four entry points

​Starter templates

​Installation

​Licensing & security

​CSS

​Next steps

Embedded Player

Custom Flow

Branding

Server client

The four entry points

Starter templates

Installation

Licensing & security

CSS

Next steps