jiayang.json

jiayang.json sits in the directory you deploy and tells jiayang deploy what the directory can’t say on its own. Every setting in it is optional apart from version, and each one overrides only what detection would have decided.

When to write one

Most apps need no jiayang.json. Write one when:

• detection picks the wrong kind, and you’d rather not pass --kind every time;
• a site’s build writes somewhere other than dist, build, out, _site, .output/public, .vitepress/dist or docs/.vitepress/dist;
• a Worker’s entry isn’t where detection looks, or it needs a compatibility date or flag;
• a container listens on a port other than 8080, runs at a size other than basic, or starts with a command detection can’t work out.

Every deploy from the directory, including one an agent runs, reads the same file. A flag only lasts one deploy.

A static site

A VitePress site whose build script isn’t called build:

{
  "version": 1,
  "build": {
    "command": "npm run docs:build",
    "output": "docs/.vitepress/dist"
  }
}

jiayang detect

a static site, served by Workers (VitePress)
  because package.json depends on vitepress, builds with `npm run docs:build`, deploys docs/.vitepress/dist/
  install: npm ci
  build: npm run docs:build
  deploys: docs/.vitepress/dist/

build.output is the directory whose files are served. Static sites covers what’s left out of it.

A Worker

A TypeScript Worker whose entry is src/worker.ts, with Node’s APIs turned on:

{
  "version": 1,
  "worker": {
    "main": "src/worker.ts",
    "compatibility_date": "2026-09-01",
    "compatibility_flags": ["nodejs_compat"]
  }
}

With no wrangler config in the project, a .ts entry is built with wrangler from a config written for the build and thrown away after.

A project with more than one wrangler config names the one to build with:

{ "version": 1, "worker": { "wrangler_config": "wrangler.production.jsonc" } }

The file has to sit beside the app and end in .json, .jsonc or .toml. Workers and frameworks covers what a wrangler config may ask for.

A container

A FastAPI app whose module isn’t main.py at the top of the project, run at the smaller lite size:

{
  "version": 1,
  "container": {
    "start": "uvicorn api.main:app --host 0.0.0.0 --port $PORT",
    "port": 8080,
    "instance_type": "lite"
  }
}

a container (FastAPI)
  because it has requirements.txt, runs as a python container
  port: 8080
  start: uvicorn api.main:app --host 0.0.0.0 --port $PORT

start and runtime only apply when the project has no Dockerfile of its own. port and instance_type apply either way. Containers has the defaults for each runtime.

What wins

From highest to lowest:

1. A flag on jiayang deploy: --kind, --main, --compatibility-date, --port, --instance-type.
2. jiayang.json.
3. The project’s wrangler config, for a Worker built with wrangler: its main, compatibility_date and compatibility_flags.
4. Detection and the defaults.

A flag lasts one deploy. The next plain jiayang deploy, or one from the dashboard’s instructions or an agent, goes back to jiayang.json.

A container’s port and size are the exception when jiayang.json doesn’t set them. Then a deploy keeps what the live version has, so --port 3000 once stays until something else sets the port. The deploy says where each value came from:

It listens on port 3000, kept from the version that was live. It runs at size basic.

Check it before you deploy

jiayang detect reads jiayang.json, so a mistake shows up before anything builds. Every section refuses fields it doesn’t know, so a typo is an error rather than a setting that does nothing:

error: jiayang.json isn't valid: unknown field `compatibility_dat`, expected one of `main`, `compatibility_date`, `compatibility_flags`, `include`, `wrangler_config` at line 1 column 47

The other checks it makes up front:

error: jiayang.json needs "version": 1
error: jiayang.json says version 2; this jiayang understands version 1
error: jiayang.json asks for the compatibility flag streams_enable_constructors, which this platform doesn't allow. Allowed: nodejs_compat, nodejs_compat_v2, nodejs_als, global_fetch_strictly_public.
error: jiayang.json's container.instance_type is "standard", which isn't a size the platform runs. Use one of lite, basic, standard-1, standard-2, standard-3, standard-4.
error: jiayang.json's wrangler_config is config/wrangler.jsonc; it names a file beside the app, like wrangler.jsonc

The old flat format

An earlier jiayang.json had no sections: main, compatibility_date, include, port and instance_type sat at the top level. That file is refused, with the same settings rewritten in the current format for you to paste:

error: jiayang.json is in the old format. Rewrite it as:

{
  "version": 1,
  "worker": {
    "main": "dist/index.js"
  },
  "container": {
    "port": 3000
  }
}

Every field

The jiayang.json schema lists each field with its type, its default and what it overrides.