/nuxt-protokit

name: nuxt-protokit
description: Use when building schema-driven prototypes with nuxt-protokit (@websideproject/nuxt-protokit) - provides definePrototype, usePrototype, ProtoTool, collections, derived values, and visualizations for rapid SaaS tool prototyping.
license: MIT

nuxt-protokit

Schema-driven rapid prototyping for Nuxt 4. Turn a TypeScript schema into a persistent, interactive SaaS tool in minutes — backed by Y.js CRDT + IndexedDB, auto-synced across tabs, with optional server sync.

When to Use

• Defining a `PrototypeSchema` with fields, collections, derived values, or visualizations
• Writing `usePrototype()` or `useProtoCollection()` composables
• Using `<ProtoTool>`, `<ProtoDashboard>`, `<ProtoCrudModal>`, `<ProtoCalendar>`, `<ProtoViz>` components
• Configuring offline persistence, encryption, namespace isolation, or corruption recovery
• Creating custom field/viz extensions with `defineProtokitExtension`
• Using headless mode (`defineHeadlessSchema`) without UI components

Quick Start

// schema.ts
import { definePrototype } from '@websideproject/nuxt-protokit'

export const schema = definePrototype({
  key: 'my-tool',
  title: 'My Tool',
  shortTitle: 'My Tool',
  description: 'Description',
  icon: 'i-heroicons-calculator',
  fields: {
    revenue:  { type: 'number', label: 'Revenue',  default: 0, format: 'money' },
    growth:   { type: 'range',  label: 'Growth %', default: 10, min: 0, max: 100 },
    plan:     { type: 'select', label: 'Plan',     default: 'starter',
                options: ['starter', 'pro', 'enterprise'] },
  },
  derived: {
    projectedRevenue: {
      deps: ['revenue', 'growth'],
      compute: ctx => ctx.fields.revenue * (1 + ctx.fields.growth / 100),
    },
  },
})

<!-- pages/my-tool.vue -->
<script setup>
import { schema } from '~/schema'
const proto = usePrototype(schema)
</script>

<template>
  <ProtoTool :schema="schema" :prototype="proto" />
</template>

Available Guidance

| File | Topics | |------|--------| | **[references/schema.md](references/schema.md)** | PrototypeSchema, all field types, CollectionSchema, DerivedDef, DashboardLayout, ProtoAction | | **[references/composables.md](references/composables.md)** | usePrototype, useProtoCollection, useProtoDoc, namespace, encryption options | | **[references/components.md](references/components.md)** | ProtoTool, ProtoDashboard, ProtoCrudModal, ProtoCalendar, ProtoViz, ProtoActionBar | | **[references/visualizations.md](references/visualizations.md)** | All 12 viz types with config interfaces and examples | | **[references/offline-first.md](references/offline-first.md)** | Y.js + IndexedDB, multi-tab sync, encryption, corruption recovery, server sync | | **[references/extensions.md](references/extensions.md)** | defineProtokitExtension, custom field/viz type registration | | **[references/headless.md](references/headless.md)** | defineHeadlessSchema, programmatic usage without UI components | | **[references/module-authoring.md](references/module-authoring.md)** | Building a Nuxt module that ships custom fields/viz: protokit:register-extension hook, plugin pattern |

Progressive Loading

Load only what you need:

• Defining fields, collections, or layout? → [references/schema.md](references/schema.md)
• Writing `usePrototype` or composable options? → [references/composables.md](references/composables.md)
• Using `<ProtoTool>`, `<ProtoCrudModal>`, `<ProtoCalendar>`? → [references/components.md](references/components.md)
• Configuring `visualizations: []` in schema? → [references/visualizations.md](references/visualizations.md)
• Encryption, multi-tenant, corruption? → [references/offline-first.md](references/offline-first.md)
• Custom field or viz type? → [references/extensions.md](references/extensions.md)
• No UI, programmatic storage? → [references/headless.md](references/headless.md)
• Building a Nuxt module that ships extensions? → [references/module-authoring.md](references/module-authoring.md)

**DO NOT read all files at once.** Load based on current task.

Related Skills

• **`nuxt`** — Nuxt 4 routing, server routes, middleware
• **`nuxt-ui`** — @nuxt/ui components for surrounding page layout
• **`vue`** — Vue 3 composables, reactivity patterns

Module Config (`nuxt.config.ts`)

export default defineNuxtConfig({
  modules: ['@websideproject/nuxt-protokit'],
  protokit: {
    serverSync: true,          // default — syncs to /api/yjs
    // serverSync: false       // local-only, no HTTP
    // serverSync: { enabled: true, baseUrl: '/api/yjs' }
  }
})

_Token efficiency: Main skill ~400 tokens. Each reference file ~800–1400 tokens._