
modelence
Build Modelence apps with correct framework patterns: rules, working examples, and Modelence docs access.
- GitHub stars
- 436
Install
/plugin install modelence@modelenceRun it inside Claude Code after adding the marketplace with /plugin marketplace add modelence/modelence.
Contents
Discovered from sourceSkills 2
Expo Router rules (Modelence mobile)
Violations of these rules cause "Unmatched Route" errors that type-checking cannot catch.
URL rules
(name)folder segments are groups — they are stripped from the URL.app/(tabs)/portfolio.tsxis reachable at/portfolio, never/(tabs)/portfolioor/tabs/portfolio.index.tsxinside any folder represents that folder's own URL.app/(tabs)/index.tsxresolves to/.- Exactly one file may resolve to
/. If you add(group)/index.tsxas the default screen, you MUST deleteapp/index.tsx. Two files resolving to the same route is undefined behavior. - Never redirect to a screen's basename. Derive
hreffrom the file path with groups stripped:app/(tabs)/markets.tsx→href="/markets",app/(tabs)/index.tsx→href="/".
Canonical tabs-without-auth structure
When the app does not require auth gating, the correct file layout is:
mobile/app/
├── _layout.tsx # Slot + providers — NO index.tsx at this level
└── (tabs)/
├── _layout.tsx # <Tabs />
├── index.tsx # default tab, URL = "/"
└── <screen>.tsx # other tabs, URL = "/<screen>"
Do NOT create app/index.tsx alongside (tabs)/index.tsx. The (tabs)/index.tsx already owns /.
Pre-completion checklist for mobile changes
Before reporting mobile work as done, verify ALL of the following:
- Every
<Redirect href="...">androuter.push("...")literal maps to a real file undermobile/app/with groups stripped. - Exactly one file resolves to
/across all ofapp/and its group subdirectories. - Run
npx tsc --noEmitinsidemobile/and fix all errors. - TypeScript passing says nothing about Expo Router's route graph — state explicitly that runtime verification requires opening the app in the mobile preview.
Modelence patterns
Reference implementations for the core Modelence building blocks. Match these patterns exactly — argument validation with zod, auth checks with AuthError, ownership verification, and typed client calls.
Example Module (src/server/example/index.ts)
import z from 'zod';
import { AuthError, time } from 'modelence';
import { Module, ObjectId, UserInfo, getConfig, Store, schema } from 'modelence/server';
const dbExampleItems = new Store('exampleItems', {
schema: {
title: schema.string(),
createdAt: schema.date(),
userId: schema.userId(),
},
indexes: [{ key: { userId: 1 } }]
});
const dailyTestCron = {
description: 'Daily cron job example',
interval: time.days(1),
handler: async () => {
// Any code written here will run daily.
},
};
export default new Module('example', {
configSchema: {
modelenceDemoUsername: {
type: 'string',
default: 'demo@modelence.dev',
isPublic: true,
},
modelenceDemoApiKey: {
type: 'secret',
default: '',
isPublic: false,
},
itemsPerPage: {
type: 'number',
default: 5,
isPublic: false,
},
},
stores: [dbExampleItems],
queries: {
getItem: async (args: unknown, { user }: { user: UserInfo | null }) => {
if (!user) {
throw new AuthError('Not authenticated');
}
const { itemId } = z.object({ itemId: z.string() }).parse(args);
const exampleItem = await dbExampleItems.requireOne({ _id: new ObjectId(itemId) });
if (exampleItem.userId.toString() !== user.id) {
throw new AuthError('Not authorized');
}
return {
title: exampleItem.title,
createdAt: exampleItem.createdAt,
};
},
getItems: async (_args: unknown, { user }: { user: UserInfo | null }) => {
if (!user) {
throw new AuthError('Not authenticated');
}
const itemsPerPage = getConfig('example.itemsPerPage') as number;
const exampleItems = await dbExampleItems.fetch({
userId: new ObjectId(user.id),
}, { limit: itemsPerPage })
return exampleItems.map((item) => ({
_id: item._id.toString(),
title: item.title,
createdAt: item.createdAt,
}));
}
},
mutations: {
createItem: async (args: unknown, { user }: { user: UserInfo | null }) => {
if (!user) {
throw new AuthError('Not authenticated');
}
const { title } = z.object({ title: z.string() }).parse(args);
await dbExampleItems.insertOne({ title, createdAt: new Date(), userId: new ObjectId(user.id) });
},
updateItem: async (args: unknown, { user }: { user: UserInfo | null }) => {
if (!user) {
throw new AuthError('Not authenticated');
}
const { itemId, title } = z.object({ itemId: z.string(), title: z.string() }).parse(args);
const exampleItem = await dbExampleItems.requireOne({ _id: new ObjectId(itemId) });
if (exampleItem.userId.toString() !== user.id) {
throw new AuthError('Not authorized');
}
const { modifiedCount } = await dbExampleItems.updateOne({ _id: new ObjectId(itemId) }, { $set: { title } });
if (modifiedCount === 0) {
throw new Error('Item not found');
}
},
},
cronJobs: {
dailyTest: dailyTestCron
}
});
Example Page (src/client/pages/ExamplePage.tsx)
import { useCallback } from 'react';
import { useParams } from 'react-router-dom';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { modelenceQuery, modelenceMutation, createQueryKey } from '@modelence/react-query';
import { Button } from '../components/ui/Button';
type ExampleItem = {
title: string;
createdAt: Date;
};
export default function ExamplePage() {
const { itemId } = useParams<{ itemId: string }>();
const queryClient = useQueryClient();
const { data, isLoading, error } = useQuery({
...modelenceQuery<ExampleItem>('example.getItem', { itemId }),
enabled: !!itemId,
});
const { mutate: createItem, isPending: isCreatingItem } = useMutation({
...modelenceMutation('example.createItem'),
});
const invalidateItem = useCallback(() => {
queryClient.invalidateQueries({ queryKey: createQueryKey('example.getItem', { itemId }) });
}, [queryClient, itemId]);
if (isLoading) return <div>Loading...</div>;
return (
<div>
{error && <div>Error: {(error as Error).message}</div>}
{data && (
<>
<h1>{data.title}</h1>
<p>Created: {new Date(data.createdAt).toLocaleString()}</p>
</>
)}
<Button onClick={invalidateItem}>Invalidate Item</Button>
<Button onClick={() => createItem({ title: 'New Item' })} disabled={isCreatingItem}>Create Item</Button>
</div>
);
}
Migrations
Migrations are versioned data migration handlers that run once on app startup, inside the app process. They import and use Stores defined in the module's db.ts — never define a Store inside a migration file. A migration file contains only the handler logic that operates on existing Stores.
MCP servers 2
Sponsors
Details
- Marketplace
- modelence/modelence
- Source
- claude-plugins/modelence
- Category
- Community