@likec4/config

Configuration utilities and schema for LikeC4 projects.

Provides:

• Project config schema (Zod) and JSON Schema for editors
• Helpers to define TypeScript configs and reusable generators
• Runtime parsers/validators for JSON/JSON5 configs
• Node helper to load config files from disk
• Filename predicates to detect config files

Docs – https://likec4.dev/

Install

pnpm add -D @likec4/config

Recognized filenames

These are treated as LikeC4 project configuration files:

• .likec4rc
• .likec4.config.json
• likec4.config.json
• likec4.config.js
• likec4.config.mjs
• likec4.config.ts
• likec4.config.mts

See ConfigFilenames in @likec4/config and helpers isLikeC4Config(...), isLikeC4JsonConfig(...), isLikeC4NonJsonConfig(...).

Quick start

JSON/JSON5 config (e.g. .likec4rc)

{
  // optional: reference JSON Schema for editor validation
  "$schema": "node_modules/@likec4/config/schema.json",
  "name": "my-project",
  "title": "My Project",
  "exclude": ["**/node_modules/**", "**/.cache/**"]
}

TypeScript/JavaScript Config

You can define a config using TypeScript or JavaScript. The config file can be any of the following:

• likec4.config.js
• likec4.config.mjs
• likec4.config.ts
• likec4.config.mts

These config files allow you to define custom generators:

import { defineConfig } from '@likec4/config'

export default defineConfig({
  name: 'my-project',
  title: 'My Project',
  generators: {
    'hello': async ({ likec4model, ctx }) => {
      for (const view of likec4model.views()) {
        // resolve folder containing the source file of the view
        const { folder } = ctx.locate(view)
        // write view to a JSON file
        await ctx.write({
          path: [folder, 'views', `${view.id}.json`],
          content: JSON.stringify(view.$view),
        })
      }
    },
  },
})

You can run your generator via CLI:

likec4 gen hello

In multi-project workspace use:

likec4 gen hello --project my-project
# Other options
likec4 gen hello --project my-project --use-dot

There is also helper function defineGenerators to define reusable generators:

// shared_generators.ts
import { defineGenerators } from '@likec4/config'

export default defineGenerators({
  'hello': async ({ likec4model, ctx }) => {
    await ctx.write({
      path: 'hello.txt', // relative to the project root
      content: `Project: ${likec4model.project.id}`,
    })
  },
})

// likec4.config.ts
import { defineConfig } from '@likec4/config'
import generators from './shared_generators'

export default defineConfig({
  name: 'my-project',
  title: 'My Project',
  generators,
})

Programmatic usage

Validate/parse JSON config

import { validateProjectConfig } from '@likec4/config'

const json = `
{
  name: "my-project" // JSON5 is supported
}
`
const cfg = validateProjectConfig(json)
// or
const cfg2 = validateProjectConfig({ name: 'my-project' })

Load config from TypeScript/JavaScript

Available only in Node.js via @likec4/config/node:

import { loadConfig } from '@likec4/config/node'
import { URI } from 'vscode-uri'

const uri = URI.file('/path/to/likec4.config.ts')
const project = await loadConfig(uri)

Detect config filenames

import { ConfigFilenames, isLikeC4Config, isLikeC4JsonConfig, isLikeC4NonJsonConfig } from '@likec4/config'

for (const name of ConfigFilenames) {
  if (!isLikeC4Config(name)) {
    // handle other files
  }
  if (isLikeC4JsonConfig(name)) {
    // handle JSON config
  }
  if (isLikeC4NonJsonConfig(name)) {
    // handle TS/JS config
  }
}

JSON Schema

The JSON Schema is published at @likec4/config/schema.json and mirrors the Zod schema.

Fields:

• name (required): unique project id within the workspace
• title (optional): human-readable project title
• contactPerson (optional): maintainer/author
• exclude (optional): array of glob patterns (picomatch) to exclude (defaults to ['**/node_modules/**'])

Getting help

We are always happy to help you get started:

• Join Discord community – it is the easiest way to get help
• GitHub Discussions – ask anything about the project or give feedback

Contributors

Become a contributor

Support development

LikeC4 is a MIT-licensed open source project with its ongoing development made possible entirely by your support.
If you like the project, please consider contributing financially to help grow and improve it.
You can support us via OpenCollective or GitHub Sponsors.

License

This project is released under the MIT License