Trellis

Opinionated app framework for repeated Nuxt + Convex apps.

Trellis gives teams one app shape for browser UI, Nitro routes, Convex functions, Better Auth, permissions, destructive operations, and MCP tools. Use it when the app needs shared backend rules across surfaces and you do not want each project to invent its own auth, access, and feature layout.

• Documentation
• Examples
• Architecture
• Security
• Roadmap
• 0.2 Workpackages
• ADRs
• RFCs
• Contributing
• Development

Quick Start

Create a starter app:

pnpm dlx @lupinum/trellis init my-app
cd my-app
pnpm install
pnpm dev

Add capabilities only when the product needs them:

trellis add auth
trellis add workspace
trellis add mcp

Presets remain shortcuts for generated fixtures, but the normal path is the ladder: start public, then add auth, workspace, and MCP as real requirements appear.

If you are adding Trellis to an existing Nuxt app instead:

pnpm add convex @lupinum/trellis

export default defineNuxtConfig({
  modules: ['@lupinum/trellis'],
  trellis: {
    url: process.env.CONVEX_URL,
  },
})

Then run:

pnpm dlx @lupinum/trellis doctor

What You Get

• Nuxt module setup and generated Convex aliases.
• Convex client/server helpers for live queries, mutations, and actions.
• Better Auth integration and identity forwarding.
• Permission-aware composables and backend access projection.
• Operation primitives for preview, confirmation, and execute flows.
• MCP helpers for tools, prompts, resources, and runtime checks.
• Starter fixtures, ladder generators, examples, lint rules, and doctor.

Good Fit

Use Trellis when:

• the app is on Nuxt + Convex + Better Auth already
• one backend model needs to serve browser UI, Nitro routes, and MCP
• isolation, roles, permissions, or destructive-work safety are real product requirements
• you want the CLI, examples, and guardrails to push the team toward one consistent shape

Skip it when:

• raw Convex is enough for a small public or one-off internal app
• you want an unopinionated helper layer instead of a framework
• you plan to discard the canonical layout immediately
• the app does not need shared auth, permission, or MCP conventions across surfaces

Canonical Shape

Generated apps converge on this layout. Public apps omit auth and permission folders until those capabilities are added.

nuxt.config.ts
convex/
  auth.ts
  auth.config.ts
  convex.config.ts
  functions.ts
  http.ts
  schema.ts
  auth/
  permissions/
  features/
shared/
  features/
app/
  features/
  pages/
server/
  api/
  mcp/

Keep routes thin and put product behavior under feature folders. Treat each top-level feature as a small Trellis boundary: runtime-neutral contracts in shared/features, backend behavior in convex/features, and UI-specific code in app/features.

Runtime Model

Trellis keeps one protected backend decision path:

1. caller
2. appIdentity
3. guard
4. load
5. authorize
6. handler

The same business model is then projected into browser UI, server callers, and MCP tools. Cross-surface destructive flows, especially MCP, should use operation-backed preview, confirmation, and execute steps.

Repository Packages

• @lupinum/trellis: Nuxt module, runtime helpers, CLI, starters, and MCP primitives for app teams.
• @lupinum/trellis-bridge: package-author utilities for Convex component-backed integrations that generate host bridge files.
• @lupinum/trellis-eslint: repository lint rules for Trellis app and example boundaries.

Normal app code should start with @lupinum/trellis. The bridge package is for integration authors, not day-one app setup.

Examples

Read these in order:

1. examples/01-public-todo
2. examples/02-auth-todo
3. examples/03-team-workspace
4. examples/04-saas-platform

Then branch into advanced references:

• examples/05-visibility-access
• examples/06-multi-workspace
• examples/07-mcp-reference
• examples/08-component-mini-cms

labs/ contains exploratory material and is not part of the maintained public learning path.

Local Development

corepack enable
pnpm install
pnpm dev
pnpm run check

Use CONTRIBUTING.md for contribution rules and DEVELOPMENT.md for the full local command map.