@jakubmazanec/carson v0.2.0

@jakubmazanec/carson

Installation

npm install @jakubmazanec/carson -g

⚠️ This is an ESM package! It cannot be required from a CommonJS module.

Prerequisites

• Node.js 16 or later

Usage

Software development is constantly evolving and best practices often change. If you want to migrate to a new tool, or merely update some settings, it can be time-consuming to do it in multiple repositories. Instead, Carson lets you write and use a template that defines what files should exist and what content should they have. Instead of updating files in your repositories manually, you change only the template and Carson handles the updates automatically for you, and keeps every repository in sync. With a template, creating new projects is also super fast and simple.

Quick overview

Update workspace:

npx carson update workspace

Create a new project in an existing workspace:

npx carson create project

See CLI documentation for the complete overview.

How it works

Carson assumes your codebase is organized in a workspace, which is simply a directory, and also usually a git repository, that contains one or multiple projects. A project is a self-contained piece of code, e.g. a package, or an app.

⚠️ Currently only Node.js projects are supported.

Take a look at this simplified example of a workspace:

workspace/
├── .carson/
│   ├── .snapshots
│   └── workspace.json
├── packages/
│   ├── foo/
│   │   ├── .carson/
│   │   │   ├── .snapshots
│   │   │   └── project.json
│   │   ├── src/
│   │   │   └── main.js
│   │   └── package.json
│   └── bar/
│       ├── .carson/
│       │   ├── .snapshots
│       │   └── project.json
│       ├── src/
│       │   └── main.js
│       └── package.json
└── package.json

Notice that the workspace and each of the two packages in it (foo and bar) have a directory named .carson with 2 files:

1. Configuration file, which specifies the ID of the Carson template that is used to define the files (or just some parts of the files) in the workspace or the project.
2. Snapshots file with all the information necessary to revert any changes.

Let's say config files workspace/packages/foo/.carson/project.json and workspace/packages/bar/.carson/project.json both contain this:

{
  "template": "carson-templates:project"
}

That means they're using a Carson template named project from a package named carson-templates. Carson template is just a directory containing *.ejs files parsed and rendered via @jakubmazanec/template package; these files are actually EJS templates with YAML front matter. Please read @jakubmazanec/template documentation to find out in more detail how they work. Simply, they're for generating content using JavaScript as a templating language.

Yes, each "Carson template" is composed of multiple "EJS templates". Hopefully, the existence of these two different template "types" isn't very confusing.

Take a look at this simplified example of carson-templates with two templates named workspace and project:

carson-templates@1.0.0
└── templates
    ├── project
    │   └── package.json.ejs
    └── workspace
        └── package.json.ejs

Because we're interested in the project template, let's see file carson-templates@1.0.0/templates/project/package.json.ejs:

---
to: 'package.json'
strategy: merge
---
{
  "repository": {
    "directory": "<%- project.relativePath %>"
  },
  "type": "module",
  "exports": "./dist/main.js",
  "files": [
    "dist",
    "src"
  ],
  "scripts": {
    "build": "swc src -d dist"
  },
  "devDependencies": {
    "@swc/cli": "^0.1.62",
    "@swc/core": "^1.3.56"
  }
}

When Carson performs a workspace update, carson-templates:project template is rendered for each project that uses it, and foo, and bar have their files changed accordingly. In this example that means foo/package.json and bar/package.json are recursively merged with the JSONs obtained from the EJS template above (so SWC is added to development dependencies, or field repository.directory is set to always be the value of a variable project.relativePath, i.e. 'packages/foo' or 'packages/bar'). Updating the workspace works the same way (although using a different Carson template, e.g. carson-templates:workspace).

When you install a newer version of carson-templates that e.g. replaces SWC with another tool, before Carson does fresh update, it first uses saved (and committed to git) snapshots from the previous update to revert all its changes. This way you don't need to keep the previous version of carson-templates around and the updates can be always done automatically from the current state of the workspace.

The fact that EJS templates are just JavaScript means Carson can support almost any use case. For that, there are also more Carson template features you need to learn than this example showcases: mainly additional strategies (you can e.g. instead of merging simply overwrite the whole file, or just create a file with some default content and then let the user change it freely) and what variables with what information is available during EJS template rendering. Please read Carson templates documentation to find out in more detail how they work, or see @jakubmazanec/carson-templates for examples.

Documentation

API

See API reference for auto-generated documentation.

Configuration

Carson configuration files are located in a directory named .carson directory. Files named workspace.json and project.json are used to configure workspace and project respectively (in case of single-project workspace they're both in the same .carson directory).

You can add arbitrary data to these JSONs in addition to the options described below. Because workspace and project configurations are available as JavaScript variables during the rendering of Carson templates, they can be used to store ad-hoc data or to allow custom, per-project configuration.

workspace.json

project.json

CLI

update workspace [<options>]

Updates workspace and all projects using the configured Carson templates.

create project [<options>]

Creates a new project in a workspace.

create workspace [<options>]

Creates new workspace.

Carson templates

🚧 This section is under development. Please check back later for updates.

Contributing

If you want to contribute, see CONTRIBUTING for details.

License

This package is licensed under the GNU Affero General Public License v3. See LICENSE for details.