Build Modelence apps with correct framework patterns: rules, working examples, and Modelence docs access.

GitHub stars
436

Install

/plugin install modelence@modelence

Run it inside Claude Code after adding the marketplace with /plugin marketplace add modelence/modelence.

Contents

Discovered from source

Skills 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.tsx is reachable at /portfolio, never /(tabs)/portfolio or /tabs/portfolio.
  • index.tsx inside any folder represents that folder's own URL. app/(tabs)/index.tsx resolves to /.
  • Exactly one file may resolve to /. If you add (group)/index.tsx as the default screen, you MUST delete app/index.tsx. Two files resolving to the same route is undefined behavior.
  • Never redirect to a screen's basename. Derive href from 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:

  1. Every <Redirect href="..."> and router.push("...") literal maps to a real file under mobile/app/ with groups stripped.
  2. Exactly one file resolves to / across all of app/ and its group subdirectories.
  3. Run npx tsc --noEmit inside mobile/ and fix all errors.
  4. 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.

Sponsors

Details

Marketplace
modelence/modelence
Source
claude-plugins/modelence
Category
Community