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.
Formats
Section titled “Formats”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`. |
managed
Section titled “managed”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` });seeded
Section titled “seeded”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).
merged
Section titled “merged”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
nullin 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:
{ "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:
{ "extends": null }To change the extends list, give the whole array: arrays replace.
Drift behaviour at a glance
Section titled “Drift behaviour at a glance”| 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.
Gotchas
Section titled “Gotchas”- 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.
.nvmrcabove istextand 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.