Configuration

Compile entry (mask.compile.cjs)

Why: Your settings and secrets live in JavaScript so you can read process.env and share one file with your team. Add dotenv at the top of this file if you want .env loaded before overrideConfig is built. Run node mask.compile.cjs whenever models, queries, or this config change.

'use strict';

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

const path = require('path');
const { runWithMaskConfig } = require('@local/mask/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: '',
      modelPaths: ['src/tables.js'],
      queryPaths: ['src']
    }
  });
}

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

Required: database

Set database to "mongodb". The compiler generates MongoDB queries and expects a getDB() export.

{
  "database": "mongodb",
  "dbModulePath": "src/db",
  "syncApiKey": "YOUR_PROJECT_API_KEY",
  "modelPaths": ["src/tables.js"],
  "queryPaths": ["src"]
}

Required: dbModulePath

The path from your project root to the module that exports your database connection (for example, src/db).

DB module (MongoDB)

Export getDB() returning a MongoDB Db instance (or Promise of it).

const { MongoClient } = require('mongodb');

let client;
let db;

async function getDB() {
  if (db) return db;
  const uri = process.env.MONGO_URI || 'mongodb://localhost:27017';
  client = new MongoClient(uri);
  await client.connect();
  db = client.db(process.env.MONGO_DB_NAME || 'myapp');
  return db;
}

module.exports = { getDB };

syncApiKey

Your Mask Databases project API key. Pass it as syncApiKey inside overrideConfig in mask.compile.cjs (for example process.env.MASK_SYNC_API_KEY).

Optional: customClassNames

If you import the Mask runtime under a different identifier than MaskDatabase or MaskModels (for example import { MaskDatabase as Db } or const Schema = require('@mask/models')), list those names under customClassNames inside overrideConfig in mask.compile.cjs so the compiler can find .prompt(...) and .define(...) calls when scanning your code.

customOnly — If true, the compiler matches only the names in customNames (it will not look for MaskDatabase or MaskModels). If false, it matches the built-in names and every name in customNames.

customNames — Array of identifiers exactly as used in source (e.g. Db.prompt('...'), Schema.define('...')). If customOnly is true, this array must not be empty.

{
  "database": "mongodb",
  "dbModulePath": "src/db",
  "syncApiKey": "YOUR_PROJECT_API_KEY",
  "customClassNames": {
    "MaskDatabase": {
      "customOnly": false,
      "customNames": ["Db", "AppDB"]
    },
    "MaskModels": {
      "customOnly": false,
      "customNames": ["MyModels", "Schema"]
    }
  }
}

Config reference

Optional: modelPaths and queryPaths

You can restrict which files or folders the compiler scans for model and query definitions. Each key is an array of strings (paths relative to your project root). Paths can be files (e.g. app/entities/User.js) or directories (e.g. src/models); directories are recursed with standard ignores.

modelPaths — Where to find MaskModels.define(...). If omitted, the whole project is scanned (excluding node_modules, .git, .mask, dist, build, etc.).
queryPaths — Where to find MaskDatabase.prompt(...). If omitted, the whole project is scanned with the same excludes.

Example

{
  "database": "mongodb",
  "dbModulePath": "src/db",
  "syncApiKey": "mc_xxxxxxxxxxxx",
  "modelPaths": ["src/models", "lib/schemas", "app/entities/User.js"],
  "queryPaths": ["src", "lib/api", "app/queries.js"],
  "customClassNames": {
    "MaskDatabase": { "customOnly": false, "customNames": ["Db"] },
    "MaskModels": { "customOnly": false, "customNames": ["MyModels"] }
  }
}

Behavior

• The compiler requires database, dbModulePath, and syncApiKey.
• dbModulePath points to your DB module so Mask can connect to your database at runtime.
• mask-sync-fetch / mask-sync-push use the same key. Add .mask/ to .gitignore and use sync to share compiled data across machines.
• Optional modelPaths and queryPaths limit which files or folders the compiler scans for definitions.
• Optional customClassNames lets you use import aliases (e.g. Db instead of MaskDatabase).