Installation
Install and configure @ontosdk/next in your Next.js project.
Currently 1.6.6. The SDK is in production use. Pin a minor version in package.json for stable upgrades.
Requirements
| Requirement | Version | Notes |
|---|---|---|
| next | 14.0.0+ | App Router required |
| node | 18.0.0+ | For Edge Runtime compatibility |
| Deployment | Vercel | Other platforms: community support only |
Install
bash
npm install @ontosdk/next
# or
pnpm add @ontosdk/next
# or
yarn add @ontosdk/next@ontosdk/core is pulled in as a transitive dependency — you don't need to install it directly unless you want to call the cleaning engine outside the SDK.
Build script
Add the onto-next CLI to your build. It walks Next's compiled HTML output and writes clean .md siblings into public/.onto/, then syncs the manifest to the Control Plane.
package.json
"scripts": {
"build": "next build && onto-next"
}Environment variables
Add your per-site API key from /serve/settings in the dashboard. The Control Plane URL defaults to api.buildonto.dev — override only if you self-host.
.env.local
# Required: per-site API key from /serve/settings
ONTO_API_KEY=onto_site_xxxxxxxxxxxxxxxxxxxx
# Optional: override Control Plane URL (default: https://api.buildonto.dev)
ONTO_API_URL=https://api.buildonto.devNever expose your API key. Do not prefix with
NEXT_PUBLIC_ — that would leak it to the browser. The SDK reads it server-side only (middleware + build CLI).Legacy env name:
ONTO_DASHBOARD_URL still works for backward compat (pre-1.6.4 sites). ONTO_API_URL is preferred going forward — same value, clearer name.