Todo App - Modelence

In this tutorial, we’ll build a complete Todo app using Modelence. You’ll learn how to:

Create MongoDB stores with TypeScript schemas
Build modules with queries and mutations
Create React components that interact with your backend

This tutorial assumes you’ve already created a Modelence project and completed the setup. If you haven’t done so, please complete those steps first.

Step 1: Create a Todo Store

Stores in Modelence are MongoDB collections with built-in TypeScript support, schema and helper methods. They help you to:

Define type-safe schemas for your data
Handle CRUD operations with MongoDB
Add custom methods to your documents
Configure indexes for better performance

Set up the project structure

The recommended approach in Modelence is to group code by modules/domains into separate directories. For our Todo app, create an src/server/todo directory and add a db.ts file:

src/server/todo/db.ts

import { Store, schema } from 'modelence/server';

export const dbTodos = new Store('todos', {
  // Define the schema for your documents. Modelence schema is based on and closely resembles Zod types.
  schema: {
    title: schema.string(),
    isCompleted: schema.boolean(), 
    dueDate: schema.date().optional(),
    userId: schema.userId(), // Built-in Modelence type for user references
    createdAt: schema.date(),
  },

  // Configure MongoDB indexes
  indexes: [
    { key: { userId: 1 } },
    { key: { dueDate: 1 } },
  ],

  // Add custom methods to documents. These are available on instances
  // returned by server-side Store methods (e.g. findById, fetch).
  // They are stripped when data is serialized over the wire to the client.
  methods: {
    isOverdue() {
      return this.dueDate ? this.dueDate < new Date() : false;
    }
  }
});

Using the Store

Once defined, you can use your Store object to perform operations on your collection:

const { insertedId } = await dbTodos.insertOne({
  title: 'Buy groceries', 
  isCompleted: false, 
  dueDate: new Date('2023-01-31'),
  userId: '123',
  createdAt: new Date()
});

const todo = await dbTodos.findById(insertedId);

console.log(todo.isOverdue());

Working with Documents

Stores provide a comprehensive set of methods for working with MongoDB documents, including finding, inserting, updating, and deleting records. All methods are fully typed with TypeScript. See the Store API Reference for a complete list of available methods and their usage.

Stores automatically handle MongoDB connection management, collection provisioning and index creation. Just define your Store and start using it - Modelence takes care of the rest.

Step 2: Create a Todo Module

Modules are the core building blocks of a Modelence application. They help you organize your application’s functionality into cohesive units that can contain queries, mutations, stores, cron jobs and configurations. Create a new file at src/server/todo/index.ts:

src/server/todo/index.ts

import { Module } from 'modelence/server';
import { dbTodos } from './db';

export default new Module('todo', {
  /*
    Include the store we created earlier so it will be automatically
    provisioned in MongoDB when the server starts.
  */
  stores: [dbTodos],

  /*
    Module queries and mutations are similar to the corresponding
    concepts from GraphQL.
  */
  queries: {
    async getOne({ id }) {
      return await dbTodos.findById(id);
    },
    async getAll() {
      return await dbTodos.fetch({});
    }
  },

  mutations: {
    async create({ title, dueDate }, { user }) {
      const { insertedId } = await dbTodos.insertOne({
        title,
        dueDate,
        userId: user.id,
        isCompleted: false,
        createdAt: new Date()
      });
      return insertedId;
    },
    async update({ id, title, dueDate, isCompleted }) {
      return await dbTodos.updateOne(id, {
        $set: {
          title,
          dueDate,
          isCompleted
        }
      });
    },
    async delete({ id }) {
      return await dbTodos.deleteOne(id);
    }
  },
});

Include the Module

Now, add the Module to your main server file at src/server/app.ts:

src/server/app.ts

import { startApp } from 'modelence/server';
import todoModule from './todo';

startApp({
  modules: [todoModule]
});

As soon as your app starts, Modelence will:

Provision the dbTodos store in MongoDB
Make the queries and mutations available for calling

Step 3: Create the Frontend

Modelence is frontend-agnostic, so you are free to use any routing library you like. We will use React Router for this example, which is what’s included in the default Modelence starter.

Add a new route

Edit src/client/routes.ts to add a new route for our todos:

src/client/routes.ts

import { lazy } from 'react';

export const routes = [
  // ... your existing routes
  {
    path: '/todos',
    Component: lazy(() => import('./TodosPage'))
  },
];

Create the TodosPage component

Create a new component at src/client/TodosPage.tsx:

src/client/TodosPage.tsx

import { useState } from 'react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import {
  modelenceQuery,
  modelenceMutation,
  createQueryKey
} from '@modelence/react-query';

// Helper: Store `methods` only live on server-side document instances and
// are stripped when results are serialized over the wire. Reimplement
// `isOverdue` on the client against the plain JSON shape.
function isOverdue(todo: { dueDate?: string | Date | null }): boolean {
  if (!todo.dueDate) return false;
  return new Date(todo.dueDate) < new Date();
}

export default function TodosPage() {
  const [newTodoTitle, setNewTodoTitle] = useState('');
  const queryClient = useQueryClient();

  const { data: todos, isPending: isLoading, error } = useQuery(
    modelenceQuery('todo.getAll')
  );

  // `modelenceQuery('todo.getAll')` uses queryKey `['todo.getAll', {}]`, so
  // invalidation must match that exact shape. `createQueryKey` builds it
  // for us — passing `['todo.getAll']` would silently no-op.
  const invalidateTodos = () => {
    queryClient.invalidateQueries({ queryKey: createQueryKey('todo.getAll') });
  };

  const { mutate: createTodo, isPending: isCreating } = useMutation({
    ...modelenceMutation('todo.create'),
    onSuccess: () => {
      setNewTodoTitle('');
      invalidateTodos();
    },
  });

  const { mutate: updateTodo } = useMutation({
    ...modelenceMutation('todo.update'),
    onSuccess: invalidateTodos,
  });

  const { mutate: deleteTodo } = useMutation({
    ...modelenceMutation('todo.delete'),
    onSuccess: invalidateTodos,
  });

  const handleCreateTodo = (e: React.FormEvent) => {
    e.preventDefault();
    const title = newTodoTitle.trim();
    if (!title) return;
    createTodo({ title });
  };

  const handleToggleComplete = (todo: any) => {
    updateTodo({
      id: todo._id,
      title: todo.title,
      dueDate: todo.dueDate,
      isCompleted: !todo.isCompleted
    });
  };

  const handleDeleteTodo = (id: string) => {
    deleteTodo({ id });
  };

  if (isLoading) {
    return (
      <div className="flex justify-center items-center min-h-screen">
        <div className="text-lg">Loading todos...</div>
      </div>
    );
  }

  if (error) {
    return (
      <div className="flex justify-center items-center min-h-screen">
        <div className="text-red-500">Error: {error.message}</div>
      </div>
    );
  }

  return (
    <div className="max-w-2xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">My Todos</h1>
      
      {/* Add new todo form */}
      <form onSubmit={handleCreateTodo} className="mb-6">
        <div className="flex gap-2">
          <input
            type="text"
            value={newTodoTitle}
            onChange={(e) => setNewTodoTitle(e.target.value)}
            placeholder="Add a new todo..."
            className="flex-1 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
          />
          <button
            type="submit"
            disabled={isCreating || !newTodoTitle.trim()}
            className="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 disabled:opacity-50 disabled:cursor-not-allowed"
          >
            {isCreating ? 'Adding...' : 'Add Todo'}
          </button>
        </div>
      </form>

      {/* Todos list */}
      <div className="space-y-2">
        {todos?.length === 0 ? (
          <p className="text-gray-500">No todos yet. Add one above!</p>
        ) : (
          todos?.map((todo) => (
            <div
              key={todo._id}
              className="flex items-center gap-3 p-3 border border-gray-200 rounded-md"
            >
              <input
                type="checkbox"
                checked={todo.isCompleted}
                onChange={() => handleToggleComplete(todo)}
                className="w-5 h-5 text-blue-600"
              />
              <span
                className={`flex-1 ${
                  todo.isCompleted 
                    ? 'line-through text-gray-500' 
                    : 'text-gray-900'
                }`}
              >
                {todo.title}
              </span>
              {todo.dueDate && (
                <span className={`text-sm px-2 py-1 rounded ${
                  isOverdue(todo)
                    ? 'bg-red-100 text-red-700' 
                    : 'bg-gray-100 text-gray-600'
                }`}>
                  Due: {new Date(todo.dueDate).toLocaleDateString()}
                </span>
              )}
              <button
                onClick={() => handleDeleteTodo(todo._id)}
                className="px-3 py-1 text-red-600 hover:bg-red-50 rounded"
              >
                Delete
              </button>
            </div>
          ))
        )}
      </div>
    </div>
  );
}

Complete Example

Want to see the full working code? Check it out on GitHub, along with other examples:

Complete Todo App Example

See the complete source code for this tutorial on GitHub, including all files and additional features.

​Step 1: Create a Todo Store

​Set up the project structure

​Using the Store

​Working with Documents

​Step 2: Create a Todo Module

​Include the Module

​Step 3: Create the Frontend

​Add a new route

​Create the TodosPage component

​Complete Example

Complete Todo App Example

Step 1: Create a Todo Store

Set up the project structure

Using the Store

Working with Documents

Step 2: Create a Todo Module

Include the Module

Step 3: Create the Frontend

Add a new route

Create the TodosPage component

Complete Example