Skip to content

Managed files

Workflows are not the only files a shared package wants to control: .nvmrc, renovate.json, lint configs. But repos also need to keep their own edits. ManagedFile makes that tradeoff explicit with three modes, so a package can say “this file is ours”, “this is a starting point”, or “this is ours plus your patch”.

new ManagedFile(scope, id, {
path: '.nvmrc', // relative to the repo root
mode: 'managed', // 'managed' | 'seeded' | 'merged'
content: '22\n', // object or string
format: 'text', // 'yaml' | 'json' | 'text' (optional)
patchFile: 'x.patch.json', // merged mode only
});

ManagedFile is a construct, so it can live anywhere in the tree (typically inside a shared package’s construct) and is collected during synth. The path is normalised (\ becomes /, a leading ./ is removed). Two files, or a file and a workflow, with the same output path fail the synth with Duplicate output path.

format is inferred if omitted: .json means json, .yml/.yaml means yaml, otherwise text for string content and json for object content.

Format Rendering
text content verbatim; must be a string. No header. merged mode is not allowed (throws).
json JSON.stringify(data, null, 2) plus a trailing newline. No header (JSON has no comments). String content is parsed first.
yaml Serialised with the yaml library, no line wrapping. Gets the generated header # Generated by cikick — do not edit. Run \npx cikick synth`.unless the mode isseeded`.

The file is regenerated on every synth and overwritten. cikick check reports drift if the on-disk content differs at all, or the file is missing. Use it for files the package fully owns. All workflows are managed files.

new ManagedFile(this, 'nvmrc', { path: '.nvmrc', mode: 'managed', format: 'text', content: `${nodeVersion}\n` });

The file is written once, when it does not exist. If it exists, synth skips it and logs kept <path> (seeded); your edits are never overwritten. cikick check reports drift only when the file is missing, never because its content differs. YAML seeded files carry no header, since they are meant to be edited.

Because a seeded file is never touched again, later changes to the template do not reach existing repos. Ship those as a migration that edits the file (migrations get readFile/writeFile).

The package’s content is deep-merged with a repo-owned patch file, and the result is written like a managed file (overwritten each synth, drift-checked byte for byte). The repo edits the patch, never the output.

Merge rules (deepMerge):

  • Objects merge recursively, key by key.
  • Arrays are replaced, not concatenated or merged by index.
  • Scalars in the patch replace the base value.
  • A null in the patch deletes that key.
  • If the patch or base is not an object at the top level, the patch value wins.

The patch is parsed in the same format as the file (JSON for .json, YAML otherwise). If patchFile is not set, or the file does not exist, the base content is used unchanged. If it exists but cannot be parsed, synth throws cannot parse patchFile <path>: .... text format cannot be merged.

Example: renovate.json from @acme/wf-node-ci

Section titled “Example: renovate.json from @acme/wf-node-ci”

The package declares the base:

new ManagedFile(this, 'renovate', {
path: 'renovate.json',
mode: 'merged',
patchFile: 'renovate.patch.json',
content: {
$schema: 'https://docs.renovatebot.com/renovate-schema.json',
extends: ['config:recommended'],
'github-actions': { enabled: false }, // cikick.lock.json owns action pins
packageRules: [/* group @acme/wf-node-ci and @cikick/*, run `npx cikick update` */],
},
});

The consumer repo owns a small patch:

renovate.patch.json
{
"schedule": ["before 5am on monday"],
"labels": ["dependencies"]
}

Synth writes the combined renovate.json (with schedule and labels added after the package’s keys). To remove something the package sets, use null:

renovate.patch.json
{ "extends": null }

To change the extends list, give the whole array: arrays replace.

Mode Written by synth cikick check reports drift when
managed Always, overwritten Missing, or content differs
seeded Only if the file does not exist Missing (content is ignored)
merged Always, overwritten Missing, or content differs from base + patch

For merged, drift therefore also means “you changed the patch and did not re-run synth”, or “someone edited the output file directly”. Fix both with cikick synth.

  • Synth never deletes files. If a package stops shipping a managed file, the old one stays in the repo until removed by hand or by a migration.
  • .nvmrc above is text and so has no header; do not rely on a header to recognise generated files other than workflows and YAML.
  • The patch file is a normal repo file: commit it. It is not generated and not listed in the lockfile.