Migrating Lifecycle and Cron Workloads to a Procfile

Use a root Procfile to replace removed lifecycle and cron workloads with monolayer processes.

Procfile Requirements

A Procfile is a text file that maps process types to shell commands. monolayer reads this file during build detection and registers each command as a launch process.

Your Procfile must meet the following requirements:

• Name the file exactly Procfile, with a capital P and no file extension.
• Place the file at the root of your application.
• Start each process type at the beginning of its line without leading whitespace.
• Use letters, numbers, underscores, or hyphens in process type names.

Each line uses the following format:

<process-type>: <command>

If you define the same process type more than once, monolayer uses the last definition.

Migrating Lifecycle Workloads

This section maps each removed lifecycle workload to its monolayer Procfile process.

Removed workload	Procfile process	Execution phase
Bootstrap	bootstrap	Runs once when monolayer creates the application environment.
BeforeRollout	beforeRollout	Runs immediately before monolayer serves the new application version.
AfterRollout	afterRollout	Runs after a successful application rollout.

Creating Lifecycle Processes

Move each lifecycle workload's script value to the corresponding Procfile process.

1. Find the package script referenced by each lifecycle workload. Keep the existing command in package.json.

   {
     "scripts": {
       "db:seed": "node scripts/seed.js",
       "prepare-rollout": "node scripts/prepare-rollout.js",
       "notify-rollout": "node scripts/notify-rollout.js"
     }
   }

2. Create a root Procfile. Add the exact lifecycle process name and invoke the corresponding package script.

   bootstrap: npm run db:seed
   beforeRollout: npm run prepare-rollout
   afterRollout: npm run notify-rollout

3. Remove the old lifecycle workload files. The SDK no longer deploys lifecycle definitions from workload files.

After migration, monolayer runs each command during its defined deployment phase. The bootstrap process runs only once for each application environment.

Migrating Cron Workloads

This section converts a removed Cron workload into a standalone command with its schedule in the Procfile.

Each cron process must follow this format:

cron-<name>: SCHEDULE="<five-field-cron-expression>" <command>

The process name must start with cron- and include a name after the prefix. The SCHEDULE value must be a quoted, standard five-field cron expression.

monolayer validates the process name and schedule during the build. The build fails if the name is malformed, the schedule is invalid, or the SCHEDULE value is missing.

Creating a JavaScript Cron Process

Use compiled JavaScript when your application doesn't need a TypeScript runtime in production.

1. Move the workload's run function into an executable module. Invoke the job from the module's top level.

   import { generateReports } from "../lib/reports.js";
   
   await generateReports();

2. Compile the job for production. Include the job module in your application's TypeScript build output.

3. Add a cron process to Procfile. Copy the workload's schedule into the quoted SCHEDULE value.

   cron-reports: SCHEDULE="0 8 * * 1" node dist/jobs/reports.js

4. Remove the old cron workload file. Cron definitions in workload files aren't deployed.

After migration, monolayer runs the cron-reports command according to the 0 8 * * 1 schedule.

Running TypeScript Directly

If a cron process runs a TypeScript file directly, your application must include tsx or ts-node in dependencies. Production environments can omit devDependencies, so a development-only runtime might not be available when the cron process starts.

1. Install a TypeScript runtime as a production dependency. Choose one of the following commands.

   npm install tsx

   npm install ts-node

2. Add the TypeScript command and schedule to Procfile. Use the runtime that you installed.

   cron-reports: SCHEDULE="0 8 * * 1" tsx src/jobs/reports.ts

   cron-reports: SCHEDULE="0 8 * * 1" ts-node src/jobs/reports.ts

   If your application uses ECMAScript modules (ESM), use ts-node --esm src/jobs/reports.ts.

3. Remove the old cron workload file. Keep the schedule and command in the root Procfile.

IMPORTANT: Install the selected runtime in dependencies, not devDependencies.

Correct: npm install tsx.

Incorrect: npm install --save-dev tsx.

After migration, monolayer validates the cron definition during the build and includes the TypeScript runtime in your production installation.