laranja.config.ts

Every project has a laranja.config.ts at its root that export defaults a config object. It's a TypeScript module (loaded via tsx), so you get full type checking and can compute values if you need to.

import type { LaranjaConfig } from "@alzulejos/laranja-decorators";

const config: LaranjaConfig = {
  name: "my-api",
  // From your laranja dashboard — identifies this project on the server.
  projectId: "proj_…",
  region: "us-east-1",
  env: { LOG_LEVEL: "info" },
  // Default compute for every function (the HTTP proxy + each cron/queue).
  compute: { memory: 256, timeout: 30 },
};

export default config;

The config stays minimal because the HTTP app is declared in code with the http() marker — there's no config field for it. For a deploy with no HTTP app, just omit the marker (see workers-only deployments). Run laranja init to scaffold this file — it fills in name and projectId from the dashboard project you pick.

Fields

name

Drives the stack name (‹name›-‹stage›) and every resource name (‹name›-‹fn›-‹stage›). Choose something short and stable — renaming it after a deploy creates a new stack rather than renaming the old one.

region and profile

region falls back to AWS_REGION, then AWS_DEFAULT_REGION. If none is set, the CLI errors with a clear message. profile selects a named profile from your AWS credentials file; otherwise the default credential chain is used.

stage

The default is "dev". It's part of resource names and is injected into every function as process.env.STAGE. The --stage flag overrides it per command — the recommended way to drive multiple environments from one config.

provider

The target cloud — "aws" (the default) or "azure". Both run Express and NestJS with HTTP, crons, queues, and environment variables, from the same app code; you switch by changing this one field.

The differences are small and always explicit — nothing is silently downgraded:

See Deploying to Azure for the full picture. Setting "azure" makes the azure block required.

azure

Required when provider: "azure". Names the subscription and the already-existing resource group laranja deploys into:

const config: LaranjaConfig = {
  name: "my-api",
  projectId: "proj_…",
  provider: "azure",
  region: "westus2",
  azure: {
    subscriptionId: "00000000-0000-0000-0000-000000000000",
    resourceGroup: "my-existing-group",
  },
};

These live in their own block (rather than loose top-level keys) so Azure's identifiers can't be confused with laranja's own — projectId is your laranja dashboard project, unrelated to any cloud identifier.

cors

Cross-origin resource sharing for your HTTP app's public endpoint. Off by default — with no cors set, browsers only allow same-origin requests (calls from your server, curl, or mobile apps are unaffected either way). Opt in by listing what you want to allow:

const config: LaranjaConfig = {
  name: "my-api",
  projectId: "proj_…",
  cors: {
    allowOrigins: ["https://app.example.com"],
    allowMethods: ["GET", "POST"],
    allowHeaders: ["Content-Type", "Authorization"],
  },
};

The fields are provider-neutral, but only AWS applies them today (they configure the HTTP app's Lambda Function URL CORS). On Azure, set CORS headers in your app. cors has no effect on a workers-only deployment (there's no public endpoint to open), and setting it there is a hard error rather than a silent no-op.

compute

The default memory (MB) and timeout (seconds) applied to every function — the HTTP proxy and each cron/queue consumer. The scaffold sets { memory: 256, timeout: 30 }. This is the one place the defaults are defined; the guides link back here rather than repeating them:

const config: LaranjaConfig = {
  name: "my-api",
  projectId: "proj_…",
  compute: { memory: 512, timeout: 20 },
};

On Azure, memory is a property of the Function App, not of individual functions — the value is snapped to the nearest Flex Consumption instance size and applied app-wide (each workers() root gets its own app, so roots can differ). The deploy warns when it snaps.

resources

Per-resource overrides, keyed by resource id — http for the proxy, or the id of a cron/queue. Each entry merges field-by-field on top of compute, and queue/cron entries also accept their kind-specific knobs (e.g. a queue's visibilityTimeout). An unknown id is a hard error, so a typo can't silently no-op:

const config: LaranjaConfig = {
  name: "my-api",
  projectId: "proj_…",
  compute: { memory: 256, timeout: 30 },
  resources: {
    http: { memory: 512 },               // beefier proxy
    cleanup: { timeout: 60 },            // a slow cron by its id
    emails: { visibilityTimeout: 180 },  // a queue by its name/id
  },
};

Workers-only deployments

To deploy only your workers (@Cron / @Queue) with no HTTP app — for teams whose API is hosted elsewhere — simply don't add an http() marker. No flag is needed. See workers-only deployments.

Related

• Environment variables
• Stages & environments
• Deploying to Azure