Getting started

1. Install the Mask package

In your Node.js project, install Mask:

npm install mask-databases

The package name is mask-databases. The Copy button copies that line to the clipboard — it is not part of the command.

The package adds mask-sync-fetch, mask-sync-push, and mask-delete. Run the compiler with node mask.compile.cjs from the project root (see below).

Add .mask/ to .gitignore (important)

After your first compile or sync, Mask creates a .mask/ directory with generated code and data. Do not commit this folder — it can be rebuilt from Mask Databases with mask-sync-fetch. Add one line to your project root .gitignore:

.mask/

Keep project settings in mask.compile.cjs (overrideConfig) and secrets in .env / process.env. See Configuration for details.

Install MongoDB driver

Mask expects a MongoDB DB module that exports getDB(). Install the mongodb Node.js driver in your app:

npm install mongodb

2. Create an account

Sign up on Mask Databases. After logging in, you'll see your dashboard.

3. Create a project

In the admin panel, go to Projects and create a new project. Give it a name (e.g. your app name). Each project gets a unique API key. Copy it; you'll use it in your Mask config.

4. Configure Mask

In the project root (next to package.json), create or edit mask.compile.cjs. It must call runWithMaskConfig with overrideConfig: at minimum database, dbModulePath, and syncApiKey (typically process.env.MASK_SYNC_API_KEY). Call require('dotenv').config() at the top of this file if you want .env loaded before process.env is read.

'use strict';

// Optional — load project .env before process.env is read:
// try { require('dotenv').config(); } catch (_) {}

const path = require('path');
const { runWithMaskConfig } = require('mask-databases/compiler');

async function main() {
  const projectRoot = path.resolve(__dirname);
  await runWithMaskConfig({
    watch: process.argv.includes('--watch'),
    projectRoot,
    overrideConfig: {
      database: 'mongodb',
      dbModulePath: 'src/db',
      // Set your Mask Databases API key, e.g. process.env.MASK_SYNC_API_KEY
      syncApiKey: ''
    }
  });
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Set MASK_SYNC_API_KEY in .env or your shell to the key from step 3. See Compile entry, database, and dbModulePath for full details.

5. Sync queries across your team and environments

Mask Databases keeps your project's queries (and models) in one place. When several people work on the same app from different laptops, everyone can stay on the same set of queries. When you deploy to production, fetch the latest so the server runs the same queries you developed.

How to do it

• Get the latest — From your project root, run npx mask-sync-fetch. Do this after you clone the repo, when a teammate has pushed new queries, or before / when deploying to production so prod has the latest queries.
• Share your changes — After you add or change queries (and run the compiler), run npx mask-sync-push. Your new or updated queries are stored in Mask Databases; others can fetch them.

Examples

• Multiple people: Alice adds a new query, runs the compiler, then npx mask-sync-push. Bob pulls the repo and runs npx mask-sync-fetch — he now has the same queries and can run the app without recompiling Alice's work.
• Deploying: Your CI or deploy script runs npx mask-sync-fetch on the production server (or in the build step) so production always gets the latest queries that the team has pushed.

For more options, see Configuration and Sync.

6. Models, queries, and compiling

In your app you define models with MaskModels.define('...') and run queries with MaskDatabase.prompt('...'). From the project root run node mask.compile.cjs (or node mask.compile.cjs --watch when your entry enables watch) so mask.compile.cjs calls runWithMaskConfig from @local/mask/compiler and turns them into runnable code. For long or reusable prompts, add a registery object inside overrideConfig in mask.compile.cjs and use mask- keys in code.

See Models, Queries, and Compiling for full details and examples.