Develop with mayura dev

mayura dev is the development loop for a Mayura project. It builds the project, runs it, and on every saved change rebuilds and restarts it. It also loads the project's .env file, so your model provider settings and other configuration reach the running code without being exported in your shell.

Every starter runs it as npm run dev:

cd refunds
npm install
npm run dev

You can also run it directly from the project directory:

npx mayura dev

#What it runs

Run mayura dev in a directory with a package.json. It then:

1. Builds the project with its build script. With no build script but a tsconfig.json, it runs tsc -p tsconfig.json. With neither, it skips the build.
2. Starts the built project, choosing the first of these that applies:
   • the file you pass with --entry <file>;
   • dist/src/dev.js, if the project has one. The starters use this for a one-process local run with demo data;
   • otherwise, the application module (--app <module>, default dist/src/app.js) the way production runs it: mayura migrate once, then mayura serve and mayura worker as two separate processes.

If there is nothing to run, it says so and keeps watching. If migrate fails, it waits for your next change.

Paths are relative to the project directory and point at built JavaScript, not TypeScript sources. For the application module's contract, see Serve, worker and migrate.

A project created from a template builds to dist/index.js, so run it with an entry:

npx mayura dev --entry dist/index.js

#.env loading

Before every build and every start, mayura dev reads .env from the project directory and passes its values to the build and to the processes it starts. Editing .env takes effect on the next restart.

• Variables already set in your environment win over the file, as with node --env-file.

• It prints only the variable names it loaded, never their values:

  Copy

    loaded .env: ANTHROPIC_API_KEY, MAYURA_MODEL, MAYURA_MODEL_PROVIDER

• node_modules/.bin is added to PATH, so build scripts find tsc and other local tools.

.env is for local development. In production, set the same variables in the real environment of your server and worker processes; mayura serve and mayura worker do not read .env.

#Watching and restarting

After the first start, mayura dev watches the project directory. When you save a file it waits 200 ms for more changes, then rebuilds:

~ src/workflow.ts changed
✔ built in 2.4s
● running dist/src/dev.js

• If the build succeeds, it stops the running processes and starts them again with the new build.
• If the build fails, it prints the last 40 lines of the build output and leaves the last good version running. Fix the error and save again.

It ignores changes the project makes to itself: node_modules, dist, .data, .git, coverage, SQLite database files, *.tsbuildinfo and *.log. It reacts only when a file's modification time or size changes, or a file appears or disappears, so merely reading files does not trigger a rebuild.

When it restarts, it asks each running process to stop and waits for it to exit. A process that has not exited after 10 seconds is killed. On Windows the process is ended directly rather than interrupted.

#Stopping

Press Ctrl+C once to stop. mayura dev stops watching and waits for the running processes to shut down gracefully; they receive the same interrupt from the terminal, so a worker can drain its in-flight work. Press Ctrl+C again to force an immediate exit.

#Good to know

• If the platform cannot watch the directory recursively, mayura dev fails with UNSUPPORTED_PROFILE. Use --no-watch.
• The serve and worker processes it starts write their own lifecycle lines to the same terminal.
• mayura dev is for your machine. For production, run mayura migrate, mayura serve and mayura worker yourself; see Serve, worker and migrate and Deployment.

#Related

• Create a project
• Serve, worker and migrate
• CLI overview
• Model providers