Arc Rider Developer Kit

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

The Arc Rider Developer Kit (ADK) gives your AI coding tool 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 in Cursor or Claude Code. 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 through chat with your AI tool.

💡 How to open the terminal: In Cursor, press Ctrl+J (Windows/Linux) or Cmd+J (Mac). In Claude Code, use your system terminal in the project folder.

🤖 Let the AI do the heavy lifting

You don't need to write NinoxScript by hand. Just describe what you want in plain language – the AI 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, your AI tool 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 in Cursor or Claude Code and start chatting!

After initialization, your AI tool 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.

Claude Code

1. Open a terminal in your project folder (after npx arc-rider-init)
2. Start Claude Code (claude)
3. Run /context and confirm Memory includes .claude/CLAUDE.md and .claude/rules/
4. Describe the widget you want – same workflow as with Cursor

Rules under .claude/rules/ are synced from the ADK on every arc-rider-init / arc-rider-update. Project-specific notes go in .claude/rules/project-rules.md (never overwritten).

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 – AI tool + Widgets (always)

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

  Cursor / Claude Code  ──→  .arc files  ──→  copy-paste into Ninox

1. Install the ADK → rules load automatically (.cursor/rules/ and .claude/)
2. Describe what you want in plain language
3. The AI 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, and database IDs (pushEnabled stays false until you opt in)
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 → copy into Ninox (default), or enable CLI push: pushEnabled: true + mode: push → npm run ninox:push -- --all

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/01-*.mdc … 07-*.mdc | NinoxScript syntax, widget references, workflow conventions | | Claude Code | .claude/CLAUDE.md, .claude/rules/*.md | Same rules for Claude Code (synced from Cursor rules) | | 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 | | Templates | docs/templates/ | Layout templates and recipes | | Dev Rules | docs/knowledge_base/development_rules_en.md | Comprehensive Ninox coding guidelines | | Spaces | spaces/ | Your Arc Rider configs (.arc) – main-<name>.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-<name>.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-dashboard.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.

Lint: NinoxScript checks

Check .arc files for common NinoxScript mistakes (deterministic, no AI):

# All spaces/**/*.arc
npm run ninox:lint

# Single file
npm run ninox:lint -- --file=spaces/dashboard/main-dashboard.arc

# JSON output (for tooling)
npm run ninox:lint -- --json

What it catches: redundant else null branches, mod(), JS comments, recordId: number(...), (select X)[...] vs where, and more — see ADK cursor rules 01-ninox-syntax-critical.mdc and 03-data-access-actions.mdc.

What it does not (yet): schema-aware checks (field/table names), full type analysis, or automatic blocking of ninox:push.

Exit code 1 when at least one error is found; warnings alone exit 0.

Maintainers: internal fixture tests for the lint rules themselves live under test/lint/ and are not part of this package.

Push & Pull: Mapping

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

mappings:
  - source: spaces/dashboard/main-dashboard.arc
    database: "1234"
    table: "Dashboard"
    field: "Cockpit Layout"
    mode: push     # requires pushEnabled: true in ninox/config.yaml

  - source: spaces/terminkalender/main-terminkalender.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.

Windows, no log entries: If status is running but project/logbook/ stays empty, check that %USERPROFILE%\.cursor\projects\<slug>\agent-transcripts exists. The slug must include the drive prefix (c-Users-...). Temporary workaround: set transcriptsPath in project/time-tracking/config.json to that folder (tilde paths supported).

💡 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-<name>.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 project-specific rules to .cursor/rules/project-rules.mdc (Cursor) and/or .claude/rules/project-rules.md (Claude Code). These files are yours – 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