yamlize

yamlize

YAML templating engine with import resolution, variable substitution, and deep merge.

Install

npm install yamlize

For CLI usage, see @yamlize/cli.

Usage

File-based (original API)

Create a meta YAML template that references other YAML fragments via import-yaml, and substitute variables with ${{yamlize.VAR}}:

meta.yaml

name: Build

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - import-yaml: node/setup.yaml
      - import-yaml: git/configure.yaml
      - name: Install and Build
        run: |
          yarn

node/setup.yaml

name: Setup Node.js
uses: actions/setup-node@v4
with:
  node-version: ${{yamlize.NODE_VERSION}}
  cache: 'yarn'

git/configure.yaml

name: Configure Git
run: |
  git config user.name "${{yamlize.git.USER_NAME}}"
  git config user.email "${{yamlize.git.USER_EMAIL}}"

import { yamlize } from 'yamlize';

yamlize('meta.yaml', 'output.yaml', {
  git: {
    USER_NAME: 'Cosmology',
    USER_EMAIL: 'developers@cosmology.zone',
  },
  NODE_VERSION: '20.x',
});

Programmatic API

Work with YAML strings or objects directly without reading/writing files:

import { yamlizeString, yamlizeObject, toYaml, fromYaml } from 'yamlize';

// Resolve template variables in a YAML string
const result = yamlizeString(
  'image: ${{yamlize.IMAGE}}',
  { IMAGE: 'nginx:1.25' }
);
// => { image: 'nginx:1.25' }

// Resolve template variables in a parsed object
const resolved = yamlizeObject(
  { name: '${{yamlize.APP}}', replicas: 3 },
  { APP: 'my-service' }
);
// => { name: 'my-service', replicas: 3 }

// Serialize / parse
const yaml = toYaml({ name: 'test', version: 1 });
const obj = fromYaml(yaml);

Deep Merge

Merge YAML/JSON objects with configurable null semantics:

import { merge, mergeNullable } from 'yamlize';

// Deep merge — null values inherit from base (default)
const merged = merge(
  { spec: { replicas: 1, image: 'nginx' } },
  { spec: { replicas: 3 } }
);
// => { spec: { replicas: 3, image: 'nginx' } }

// null in overrides is skipped, base value preserved
merge({ image: 'nginx:1.0' }, { image: null });
// => { image: 'nginx:1.0' }

// With nullRemoves: true, null deletes the key
merge({ image: 'nginx:1.0' }, { image: null }, { nullRemoves: true });
// => {}

// Shallow merge with null-skipping
mergeNullable(
  { name: 'app', replicas: 1 },
  { replicas: 5, name: null }
);
// => { name: 'app', replicas: 5 }

API

Function	Description
yamlize(inFile, outFile, context)	Read template, resolve imports + variables, write output file
yamlizeString(yaml, context, opts?)	Resolve a YAML string against a context, return parsed object
yamlizeObject(obj, context, opts?)	Resolve a parsed object against a context
toYaml(obj)	Serialize a value to YAML string
fromYaml(str)	Parse a YAML string to a value
parse(obj, dir, context)	Low-level: resolve imports + variables recursively
merge(base, overrides, opts?)	Deep merge with null-inheritance (default) or null-removes
mergeNullable(base, overrides)	Shallow merge skipping null/undefined overrides

---

Development

Setup

1. Clone the repository:

git clone https://github.com/constructive-io/dev-utils.git

1. Install dependencies:

cd dev-utils
pnpm install
pnpm build

1. Test the package of interest:

cd packages/<packagename>
pnpm test:watch

Credits

Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.