Arc Rider Developer Kit

Build professional Ninox UIs with Arc Rider Widgets and AI – powered by Cursor.

The Arc Rider Developer Kit (ADK) gives Cursor everything it needs to generate high-quality NinoxScript code for Arc Rider Widgets: syntax rules, widget docs, reference implementations, and connections to your Ninox database and Framer designs.

👋 New to the terminal? No worries.

You only need the terminal once for the initial setup – then you work entirely inside Cursor. Here are the only commands you'll ever need:

# 1. Set up your project (run once)
npm install @arcrider/developer-kit
npx arc-rider-init

# 2. Keep docs up to date when a new version is released
npx arc-rider-update

# 3. Push your widget code to Ninox
npm run ninox:push -- --all

That's it. Everything else happens in Cursor through chat.

💡 How to open the terminal: In Cursor, press Ctrl+J (Windows/Linux) or Cmd+J (Mac).

🤖 Let the AI do the heavy lifting

You don't need to write NinoxScript by hand. Just describe what you want in plain language – Cursor figures out the rest.

Examples of what you can say:

"Build a timeline view for all employees showing their appointments for the current month."

"Create a Kanban board with columns Open, In Progress and Done – filtered by the currently logged-in user."

"Make the cards clickable so a popup opens with the full record."

Through the ADK, Cursor knows all Widget APIs, NinoxScript syntax, and your database structure – and generates ready-to-use code you can paste directly into Ninox.

What the AI handles for you:

• Writing and adapting widget code
• Finding and explaining errors in existing code
• Writing database queries (select, where, relations)
• Translating Framer designs into Ninox layouts
• Adding new requirements without breaking existing code
• Generating test data via ninox:seed (API key already configured)

💡 Tip: The more context you give, the better the result. Tell the AI which tables and fields you have – or let it read your downloaded schema directly (npm run ninox:download).

Quick Start

# 1. Create a project folder
mkdir my-app && cd my-app

# 2. Install the package
npm install @arcrider/developer-kit

# 3. Initialize your project
npx arc-rider-init

# 4. Open the folder in Cursor and start chatting!

After initialization, Cursor already knows:

• All Arc Rider Widget APIs
• NinoxScript syntax rules
• Best practices and code patterns

You can start writing .arc files in spaces/ right away.

Connect your tools (all optional)

# Ninox – connect your database so Cursor knows your tables and fields
npm install @ninox/ninox
# Edit ninox/config.yaml → add API key, workspace ID, database IDs
npm run ninox:download                              # download schema (picks your DB)

# Framer – connect your designs so Cursor knows your layout and colors
npm install framer-api ws
# Edit framer/config.yaml → add API key + project URL
npm run framer:pull                                 # download design data

The Arc Rider Universe

The ADK has three orbits. Start with Level 1 and expand when you're ready.

🪐 Level 1 – Cursor + Widgets (always)

The foundation. Cursor knows all widget APIs and NinoxScript rules out of the box.

  Cursor  ──→  .arc files  ──→  copy-paste into Ninox

1. Install the ADK → Cursor reads the rules automatically
2. Describe what you want in plain language
3. Cursor generates widget code in .arc files
4. Copy the code into your Ninox formula field

No extra setup needed. This works immediately after npx arc-rider-init.

🛸 Level 2 – + Ninox Database Connection (recommended)

Let Cursor read your actual database structure. It will know your tables, fields, and relations – and generate code that fits your schema exactly.

  Ninox DB  ──→  schema download  ──→  Cursor  ──→  push back to Ninox

1. Edit ninox/config.yaml → add your API key, workspace ID, database IDs, and set pushEnabled: true
2. Download your schema: npm run ninox:download (picks your DB automatically)
3. Cursor reads the schema and understands your data model
4. Generate code → push directly: npm run ninox:push -- --all (confirms before uploading)

No more copy-pasting. Code goes straight from Cursor into Ninox.

🌌 Level 3 – + Design Tool Integration (optional)

Connect your Framer designs so Cursor knows your layout, colors, typography, and components. Currently supported: Framer.

  Framer canvas  ──→  design data  ──→  Cursor  ──→  pixel-perfect Ninox UI

1. Pull your canvas: npm run framer:pull
2. Cursor reads frames, styles, fonts, and component structure
3. Generate widget layouts that match your design system exactly

What's Included

| Component | Path | Purpose | |-----------|------|---------| | Cursor Rules | .cursor/rules/arc-rider-widgets.mdc | NinoxScript syntax, widget references, workflow conventions | | Widget Docs | docs/widgets/, docs/mini_widgets/ | Full documentation for all Arc Rider Widgets | | Framer API Ref | docs/framer-api.md | Framer Server API reference for AI agents | | Examples | docs/examples/ | Code patterns and UI recipes | | Use Cases | docs/use_cases/ | Complete reference implementations | | Dev Rules | docs/knowledge_base/development_rules_en.md | Comprehensive Ninox coding guidelines | | Spaces | spaces/ | Your Arc Rider configs (.arc) – main.arc, views/, templates/ |

Spaces

Spaces are your Arc Rider widget configurations – one folder per feature area.

# Create a new space
npx arc-rider-space dashboard

# Or interactively
npx arc-rider-space

Each space lives in spaces/<name>/main.arc with optional views/ and templates/ subfolders. See spaces/README.md for the full structure.

Ninox Workflow (optional)

Connect your Ninox database to let Cursor read your schema and push code directly.

Setup: ninox/config.yaml

After npx arc-rider-init, edit ninox/config.yaml and fill in your credentials and database IDs:

environments:
  dev:
    domain: https://api.ninox.com
    apiKey: YOUR_API_KEY_HERE
    workspaceId: YOUR_WORKSPACE_ID
    databases:
      - id: "YOUR_DATABASE_ID"
        name: "My Database"
        pushEnabled: false   # set to true to allow npm run ninox:push

Multiple databases? Add them all – the CLI will show a picker. Multiple environments (dev, staging)? Each gets its own credentials and databases.

Push safety: Push is disabled by default (pushEnabled: false). Set it to true for each database you want to push to. This prevents accidental overwrites – especially important when working with AI agents.

Download Schema

npm run ninox:download

Downloads the complete database structure as YAML to ninox/src/Objects/. If you have multiple databases configured, you'll get an interactive picker. Override with --db=ID or --env=staging.

Push & Pull

# Push a single space to Ninox
npm run ninox:push -- --file=spaces/dashboard/main.arc

# Push all mapped spaces
npm run ninox:push -- --all

# Push with environment override
npm run ninox:push -- --all --env=staging

# Push without confirmation prompt (e.g. in CI)
npm run ninox:push -- --all --yes

# Pull schema + extract formulas
npm run ninox:pull -- --extract

Push runs in 3 steps – automatically:

1. Download – Fetches the latest schema from Ninox (ensures no external changes are overwritten)
2. Inject – Writes formula(s) from local .arc files into the schema YAML
3. Upload – Pushes the complete schema back to Ninox

Before each push, you'll see a confirmation prompt listing the target environment, database, and files. Confirm with y to proceed. Skip the prompt with --yes (useful in CI or for experienced users who know what they're doing).

Requires pushEnabled: true in ninox/config.yaml for each target database. The push aborts immediately if the database is not opted in.

Seed: Test Data

Need test data? Just ask Cursor: "Create 20 test records for the Aufträge table." The AI reads your schema, generates a JSON file, and pushes it via the Ninox API – your credentials from ninox/config.yaml are already set up.

# Seed records from a JSON file
npm run ninox:seed -- --table=A --file=seed-data.json

# Delete all records first, then seed
npm run ninox:seed -- --table=A --file=seed-data.json --clean-first

# Just delete all records (asks for confirmation)
npm run ninox:seed -- --table=A --clean

# Skip confirmation with --yes
npm run ninox:seed -- --table=A --clean --yes

The database is auto-detected from ninox/config.yaml. Override with --db=ID or --env=staging if needed.

Push & Pull: Mapping

Requires ninox/ninox-mapping.yaml to map .arc files to Ninox formula fields:

mappings:
  - source: spaces/dashboard/main.arc
    database: "1234"
    table: "Dashboard"
    field: "Cockpit Layout"

  - source: spaces/terminkalender/main.arc
    mode: manual   # copy-paste into Ninox, no CLI push

Framer Workflow (optional)

Connect your Framer projects to let Cursor read your designs – layout, colors, typography, components.

Pull Design Data

# Pull all configured projects
npm run framer:pull

# Pull specific project
npm run framer:pull -- --project=hauptseite

# Test connection
npm run framer:pull -- --test

Downloads the full canvas tree (pages, frames, components with design properties), styles, and fonts to framer/src/<project>/.

Live Queries

Cursor can query Framer on-demand during a chat session:

# Find element by name
npm run framer:inspect -- --project=main --find="Header"

# Get page tree
npm run framer:inspect -- --project=main --page="/"

# Styles, fonts, sitemap
npm run framer:inspect -- --project=main --styles
npm run framer:inspect -- --project=main --tree

Multi-Project Config

# framer/config.yaml
projects:
  hauptseite:
    url: https://framer.com/projects/abc123
    apiKey: fr_xxx
  landing:
    url: https://framer.com/projects/def456
    apiKey: fr_yyy

ADK Logbook (optional)

Track your AI coding sessions automatically. The ADK Logbook watches your Cursor agent-transcripts in the background and writes human-readable daily log files – perfect for time tracking and billing.

Start / Stop

# Start the logbook service in the background
npm run arcrider:logbook start

# Check whether the service is running
npm run arcrider:logbook status

# Stop the service
npm run arcrider:logbook stop

Report

# All entries
npm run arcrider:logbook report

# Filter by month
npm run arcrider:logbook report -- --month 2026-04

Where logs are stored

project/
  logbook/                           ← gitignored
    adk_logbook_2026-04-14.jsonl     ← daily log (UTC timestamps)
  time-tracking/                     ← gitignored
    arc-rider-logbook.state.json     ← internal state (byte offsets)
    arc-rider-logbook.pid            ← PID of running service
    config.json                      ← optional config (see below)

Optional config

Create project/time-tracking/config.json to customize:

{
  "projectName": "my-project",
  "transcriptsPath": "",
  "outputDir": "project/time-tracking",
  "source": "cursor-transcript-logbook",
  "maxInitialImportBytes": 2000000
}

Leave transcriptsPath empty (or omit) to use the auto-detected Cursor path.

💡 Agent integration: Once started, Cursor will occasionally check the logbook status and offer to start it if it isn't running – without nagging on every reply.

Project Structure

my-app/
├── .cursor/rules/arc-rider-widgets.mdc  ← AI rules (auto-managed)
├── docs/                                ← Widget docs + Framer API ref (auto-managed)
├── spaces/                              ← Your .arc files (your code!)
│   ├── shared/                          ← Design system, global helpers
│   └── <name>/main.arc                  ← Per-feature entry points
├── ninox/                               ← Ninox connection (optional)
│   ├── config.yaml                      ← Credentials (gitignored)
│   ├── ninox-mapping.yaml               ← Space → Ninox field mapping
│   └── src/Objects/                     ← Downloaded schema
├── framer/                              ← Framer connection (optional)
│   ├── config.yaml                      ← Credentials (gitignored)
│   └── src/<project>/                   ← Canvas, styles, fonts
├── scripts/                             ← Custom Pro-Code (Node.js, etc.)
├── project/                             ← Design mockups, chats, references
├── .gitignore
└── package.json

Updating

When a new version of the ADK is released:

npx arc-rider-update

This updates the package and refreshes docs, rules, and scripts in one step. npx arc-rider-init --update also works.

Your custom files (configs, spaces, project context) are never overwritten.

💡 Custom rules: Add your own project-specific rules to .cursor/rules/project-rules.mdc. This file is yours – it's preserved across every update.

Git & Version Control

Your project is ready for Git (npx arc-rider-init initializes a repo automatically).

git add . && git commit -m "feat: initial Arc Rider app"

Commit messages follow Conventional Commits (feat, fix, docs, refactor, etc.) in English.

Troubleshooting

Ninox: "Push ist für Datenbank … nicht aktiviert"

Push is disabled by default. Set pushEnabled: true for the database in ninox/config.yaml:

databases:
  - id: "YOUR_DATABASE_ID"
    name: "My Database"
    pushEnabled: true

Ninox: "config.yaml not found"

After npx arc-rider-init, your config is at ninox/config.yaml. Open it and fill in your credentials (API key, workspace ID, database IDs).

Ninox: "Environment DEV not found"

Use dev (lowercase) in config.yaml. The key under environments: is case-sensitive. The --env flag also expects the exact name.

Ninox: "Access Denied"

1. Wrong domain – Use https://api.ninox.com (not app.ninox.com)
2. Invalid API key – Ninox → Settings → API Keys → Generate
3. Wrong workspaceId – Run cd ninox && ninox dev database list

Framer: "framer-api not installed"

Run npm install framer-api. On Node < 21, also npm install ws.

Framer: "config.yaml not found"

After npx arc-rider-init, your config is at framer/config.yaml. Open it and add your API key + project URL.

Links

• Arc Rider Widgets
• Framer Server API
• Ninox Script Reference
• Ninox CLI