fluent-convex

0.13.0 verified Mon Apr 27 auth: no javascript

A fluent API builder for Convex functions with composable middleware, reusable chains, and plugin support. Current stable version 0.13.0, actively maintained with monthly releases. Key differentiators: onion-style middleware composition, full type inference across chains, cross-function-type middleware via `$context`, and official plugins (e.g., fluent-convex/zod). Unlike raw Convex functions, provides a developer-friendly chainable syntax and middleware abstraction. Requires peer dependencies convex ^1.31.0, zod ^3.25.0 || ^4.0.0, convex-helpers >=0.1.0.

Common errors

error Cannot find module 'fluent-convex' or its corresponding type declarations. ↓

cause Missing types due to incorrect import path or missing tsconfig entries.

fix

Install fluent-convex and ensure tsconfig has 'moduleResolution': 'node16' or 'bundler'

error Property 'db' does not exist on type 'ActionCtx'. ↓

cause Using query-type middleware on an action.

fix

Use .$context<{ auth: Auth }>().createMiddleware() to create middleware that works across all function types.

error Type 'DataModel' could not be inferred. Please provide explicit type argument. ↓

cause Missing DataModel type parameter when calling createBuilder.

fix

Import DataModel from your convex _generated folder and pass it: createBuilder<DataModel>()

error ERR_REQUIRE_ESM ↓

cause Using require() on an ESM-only package.

fix

Change to import syntax or set { "type": "module" } in package.json.

Warnings

gotcha Middleware created with .query().createMiddleware() only works on queries (not mutations/actions) because it expects QueryCtx with db property. ↓

fix Use .$context<{ auth: Auth }>().createMiddleware() for cross-function-type middleware.

deprecated In v0.13, some internal APIs may change; always use the public builder methods. ↓

fix Check changelog for any deprecations.

breaking v0.13 requires ESM imports; CommonJS require() will throw. ↓

fix Use import syntax (ESM) or upgrade to Node 18+ with { "type": "module" }.

gotcha Forgetting the DataModel type parameter loses type inference on ctx.db queries. ↓

fix Always pass your DataModel type to createBuilder<T>()

Install

npm install fluent-convex

yarn add fluent-convex

pnpm add fluent-convex

Imports

createBuilder

wrong

const createBuilder = require('fluent-convex')

correct

import { createBuilder } from 'fluent-convex'

ESM-only. v0.13+ uses pure ESM; CommonJS require will fail.

fluent-convex/zod
wrong
```
import { zodValidator } from 'fluent-convex'
```
correct
```
import { zodValidator } from 'fluent-convex/zod'
```
Zod plugin is a separate subpath export. Must import from 'fluent-convex/zod'.

FluconvexBuilder

wrong

import { createBuilder } from 'fluent-convex'; const b = createBuilder()

correct

import type { DataModel } from './_generated/dataModel'; import { createBuilder } from 'fluent-convex'; const b = createBuilder<DataModel>()

Type parameter for DataModel is required for full type inference. Omitting it loses db query types.

Quickstart

Creates a Convex query using fluent-convex with input validation and public registration. Demonstrates createBuilder, .query(), .input(), .handler(), and .public().

import { createBuilder } from "fluent-convex";
import { v } from "convex/values";
import type { DataModel } from "./_generated/dataModel";

const convex = createBuilder<DataModel>();

export const listNumbers = convex
  .query()
  .input({ count: v.number() })
  .handler(async (ctx, args) => {
    const rows = await ctx.db.query("numbers").order("desc").take(args.count);
    return rows.map((r) => r.value);
  })
  .public();