Guides by Christian Munoz

Add a New Module to a Tauri App by Copying the Items Example

Get the Tauri Local-AI Starter Kit on Gumroad $199 one time

The problem

A new feature in a local-first app is never one file. It needs a database table that migrates safely, validation shared by the API and the assistant, a route, a page, export and import support and tests, and forgetting any of them gives you a feature that works in the demo and loses data in real use. Starting from a blank folder, you rediscover that list the hard way.

The kit ships a single example module, Items, on purpose. It touches every layer, so the fastest route is to duplicate it layer by layer and rename. The examples below use an invented module called widgets. The sequence is the same one the kit's own checklist follows, with the points where people most often slip called out. As with the rest of the kit, only Windows has been tested.

Steps

  1. Write the migration and lock its hash

    Add a file named NNN_widgets.sql in server/db/migrations/, where NNN is the next free number after the highest file already there. Compute its SHA-256 with CRLF normalized to LF and add it to server/db/migrations.lock.json. Never edit a shipped migration: a test fails if a locked file changes, and before each migration runs the app copies the database to a .bak file.

  2. Register the table

    Add the table to TABLES in server/db/tables.js, and to IMPORT_ORDER with parents before children. Tables that are not listed cannot be queried at all, because all database access goes through the allowlisted helper.

  3. Add validation, data access and routes

    Copy server/items.js for one shared definition of a valid record, add functions in server/dataAccess.js and routes like those in server/dataRoutes.js. Register the stats route before the id route so it is not swallowed.

  4. Give the assistant tools, with approval for writes

    Add tool specs to ASSISTANT_TOOLS and cases to dispatch() in server/agents/assistantTools.js. For a write tool, add its name to WRITE_TOOLS and a line to describeWrite() in pendingActions.js so the Approve card says what will happen.

  5. Map the data to a cloud category

    Add each tool and page to the maps in server/ai/privacy.js, and mirror any new category in src/constants/cloudAi.js. A tool or page missing from the maps is refused when a cloud provider is active.

  6. Build the page, then export and tests

    Add the page, components, hook and service, route it in src/App.jsx and add the page key to the two assistant-page files together. Add a definition to DATA_TABLES so the table is exported, then run npm test, npm run lint and npm run check.

What the Items example demonstrates

Items covers the migration, the table registry, validation, data access, routes, assistant tools with an approval card, cloud categories, the UI, export and import and tests. One part is a worked example of gating: a summary route that first checks a Pro capability, then checks that a model is available, then lets code compute the stats while the model only words them.

If your module has no paid feature, skip that file. Never gate the user's data, export, import or backups.

Where numbers are allowed to come from

Whenever your module shows totals, counts or averages, compute them in SQL or JavaScript and hand the model only the finished figures. Keep a test that proves the model was not asked to calculate. The kit's own stats function for items is the pattern to copy.

Pros and cons

Pros

  • Duplicating a working slice beats designing one, and every layer has a file to copy.
  • A lock file and a migration test stop you from changing history by accident.
  • Export, import and cloud-category mapping are part of the checklist, so they are not afterthoughts.
  • Approval for assistant writes comes built in rather than bolted on.

Cons

  • A module touches many files, so the first one takes real time even with a template.
  • Some lists must be kept in step by hand, such as the two assistant page files.
  • The kit ships only the Items module, so there is no library of ready-made modules to borrow from.
  • You need to be comfortable with Node, React and SQL, and the kit is tested on Windows only.

Frequently asked questions

Why is there only one example module?

The kit ships Items on purpose so the whole slice is easy to read. It is not meant to be a library of ready-made modules.

What if I edit a migration after it has shipped?

The migration safety test fails, because every shipped migration has a locked hash. Add a new numbered file instead.

Do I need a real model to run the tests?

No. Tests use a fake Ollama helper. The separate eval script is the only thing that needs a real one.

Can an assistant tool change data directly?

A write tool is parked behind a single-use token until the user clicks Approve. Running it straight from the model loop is against the kit's rules.

Get the Tauri Local-AI Starter Kit on Gumroad $199 one time