@tabularis/create-plugin

Scaffold a new Tabularis database driver plugin in seconds.

npm create @tabularis/plugin@latest my-driver

(Works the same with pnpm create @tabularis/plugin@latest my-driver or yarn create @tabularis/plugin my-driver.)

Declarative themes

The separate tabularis-theme entry point scaffolds, validates and packages themes without changing the driver command's defaults. Generated theme repositories work offline with their bundled Node tool. See the theme author guide for local preview, VS Code conversion, licensing, version gates and GitHub/Tabularium publishing. This new entry point requires the updated tooling package or a local source build; it is not assumed available in an older published version.

What you get

A runnable Rust project with:

• .tabularium bundle manifest aligned with the Tabularis plugin schema.
• 33 JSON-RPC handlers pre-wired — metadata methods return empty arrays (plugin loads cleanly), query/CRUD/DDL methods return -32601 until you implement them.
• test_connection placeholder that returns success, so your driver appears in the connection picker immediately after just dev-install.
• Working utilities: quote_identifier, paginate — with unit tests — ready to use from your handlers.
• Cross-platform GitHub Actions release workflow for Linux x64/arm64, macOS x64/arm64, and Windows x64.
• Local REPL (just repl) for debugging without restarting Tabularis.
• Optional UI extension subworkspace (--with-ui) pre-configured with Vite IIFE + @tabularis/plugin-api.

Usage

npm create @tabularis/plugin@latest [--] [options] <name>

-- separates the package name from the flags so they reach the CLI instead of npm. If you prefer the direct form:

npx @tabularis/create-plugin [options] <name>

Options

| Flag | Values | Default | Purpose | |------|--------|---------|---------| | --db-type | network | file | folder | api | network | Shapes the connection form and capabilities | | --quote | " | ` | " | SQL identifier quote character | | --with-ui | boolean | off | Also scaffold a ui/ subworkspace using @tabularis/plugin-api | | --no-git | boolean | off | Skip git init | | --dir | path | ./<name> | Target directory |

Examples

# Network driver (host/port/user/pass connection form)
npm create @tabularis/plugin@latest my-pg-like

# File-based driver (SQLite, DuckDB shape)
npm create @tabularis/plugin@latest duckdb-clone -- --db-type=file

# API-based plugin (no connection form; public REST-ish data source)
npm create @tabularis/plugin@latest my-api -- --db-type=api

# With UI extension scaffold
npm create @tabularis/plugin@latest mine -- --with-ui

Next steps after scaffolding

cd my-driver
just dev-install              # builds and installs into ~/.local/share/tabularis/plugins/my-driver
# open Tabularis → your driver is in the connection picker

From there, fill in handlers in src/handlers/metadata.rs, then query.rs, then the rest. The generated README.md includes a feature-by-feature roadmap.

Migrating an existing plugin

Plugins built before the registry cutover ship a manifest.json. The host now reads a .tabularium bundle manifest (the manifest.json path survives only as a deprecated fallback). To convert a project in place:

npx @tabularis/create-plugin migrate            # current directory
npx @tabularis/create-plugin migrate ./my-driver

This writes .tabularium from your manifest.json, removes the old file, and updates the manifest.json references in release.yml, justfile, and README.md. A legacy id that differs from name is kept for the host's benefit only — the registry has no id field and keys everything off name (the pinned lowercase slug). The command refuses to run if the manifest has no semver version, which the registry requires — without a leading v, and it must equal the release tag stripped of any v prefix.

By default the release workflow is left as-is (only its manifest.json reference is renamed so the build keeps working). The hosted Tabularium registry resolves the manifest from the release assets, so it needs .tabularium published as a standalone asset (GitHub renames the dotfile to default.tabularium on upload — the registry accepts either name). Add --ci to regenerate release.yml from the registry-ready template:

npx @tabularis/create-plugin migrate ./my-driver --ci

--ci overwrites release.yml (re-apply any custom CI steps) and derives the binary name from the manifest's executable field. Commit the result and republish.

Layout of the generated project

my-driver/
├── Cargo.toml
├── .tabularium
├── README.md
├── justfile            # just build / test / dev-install / repl / lint / fmt
├── rust-toolchain.toml
├── .github/workflows/release.yml
└── src/
    ├── main.rs         # stdio JSON-RPC loop
    ├── rpc.rs          # method dispatch
    ├── client.rs       # TODO: your DB client
    ├── error.rs
    ├── models.rs
    ├── handlers/{metadata,query,crud,ddl}.rs
    ├── utils/{identifiers,pagination}.rs
    └── bin/test_plugin.rs

With --with-ui:

my-driver/ui/
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/index.tsx     # defineSlot("data-grid.toolbar.actions", …)

Requirements

• Node 18.17 or newer.
• Rust stable (for building the generated plugin).
• just (optional but recommended — the generated justfile wraps the common tasks).

Related

• Plugin guide — authoritative reference for JSON-RPC methods, capabilities, slots.
• Manifest reference — every .tabularium field with constraints; invalid manifests are rejected at submit (HTTP 422).
• @tabularis/plugin-api — TypeScript types + hooks for UI extensions.
• Tabularis repo — the host app.

License

Apache-2.0